Board Game Arena - User contributions [en]

Table

2024-10-02T09:54:40Z

Sguzzer Gunayer:

This is reference for public and protected method defined in Table and its ancestors, this information obtained by using php reflection.

Most of these methods are documented on various other wikis, this is just reference for completeness and in case you run into accidental overloading of undocumented functions...

<span style="color:red">Its a long list please help with editing this wiki</span>

If you need these method for IDE autocompletion and validation there is unofficial project that has stubs to documented methods:
* https://github.com/elaskavaia/bga-sharedcode/blob/master/misc/module/table/table.game.php (if you want more stubs pull requests are welcome to this repository)

== Class hierarchy ==

* APP_Object
** APP_DbObject
*** APP_GameClass
**** Table - this is a class all games inherit
**** [[Deck]] - db handling component for specific schema (deck)

== Methods in the Table class ==
;Table.getGameName
:part of template, return game name, not to be modified by developer, not document on wiki
;Table._
:translation wrapper function, see [[Translations]]
;Table.setTable
:method that sets up the php side, do not call or override
;Table.initTable protected
:This method is called by framework before every action (does nothing by default), unlike constructor this method has initialized state of the table so it can access db, undocumented as it has very limited use
;Table.getAllTableDatas
:undocumented
;Table.getAllDatas
:part of template, override, see [[Main game logic: yourgamename.game.php]]
;Table.setupNewGameTable
:undocumented
;Table.setupNewGame
:part of template, override, see [[Main game logic: yourgamename.game.php]]
;Table.getTableOptionsForGame static
:undocumented
;Table.getTableOptions
:undocumented, likely return gameoptions (i.e. variants of the games)
;Table.getTablePreferencesForGame static
:undocumented
;Table.getTablePreferences
:undocumented, likely return UI preferences (i.e. display tooltips or not)
;Table.getGameInfosForGame static
:undocuments, likely return $gameinfos from gameinfos.inc.php
;Table.getGameOptionsInfos
:undocumented
;Table.start
:undocumented, likely starts the game, do not call
;Table.stMakeEveryoneActive
:this method can be used in state machine to make everybody active as "st" method of multiplayeractive state

;Table.loadPlayersBasicInfos
:very usefull function get players table, see [[Main game logic: yourgamename.game.php]]
;Table.reloadPlayersBasicInfos
:reload players info, see [[Main game logic: yourgamename.game.php]]
;Table.reattributeColorsBasedOnPreferences
:change players colors, see [[Main game logic: yourgamename.game.php]]
;Table.getBestColorFromColorPrefs
:undocumented, do not call, use to pick a color based on preference
;Table.initSetupPlayersInfos
:undocumented
;Table.getPlayersNumber
:returns number of players, see [[Main game logic: yourgamename.game.php]]
;Table.checkAction
:check action on server, see [[Main game logic: yourgamename.game.php]]
;Table.checkGameStart
;Table.color_to_color_back
:@deprecated, undocumented
;Table.initGameStateLabels
;Table.setGameStateInitialValue
:Set initial state of global, technically same as setGameStateValue see [[Main_game_logic:_yourgamename.game.php#Use_globals]]
;Table.getGameStateValue
:get value of global see [[Main_game_logic:_yourgamename.game.php#Use_globals]]
;Table.setGameStateValue
:set value of global see [[Main_game_logic:_yourgamename.game.php#Use_globals]]
;Table.incGameStateValue
:increment value of global see [[Main_game_logic:_yourgamename.game.php#Use_globals]]
;Table.is_testmode
:@deprecated
;Table.testmodedatas
:@deprecated
;Table.applyTestModeDbFixture
;Table.getActivePlayerId
:get active player id, see [[Main_game_logic:_yourgamename.game.php#Game_states_and_active_players]]
;Table.getActivePlayerName
:get active player name, see [[Main_game_logic:_yourgamename.game.php#Game_states_and_active_players]]
;Table.getCurrentPlayerId
:get current player id, see [[Main_game_logic:_yourgamename.game.php#Game_states_and_active_players]]
;Table.getCurrentPlayerName
:get currrent player name, see [[Main_game_logic:_yourgamename.game.php#Game_states_and_active_players]]
;Table.getCurrentPlayerColor
:get current player color, see [[Main_game_logic:_yourgamename.game.php#Game_states_and_active_players]]
;Table.getPlayerNameById
:get the name by id, see [[Main_game_logic:_yourgamename.game.php#Accessing_player_information]]
;Table.getPlayerColorById
:get the color by id, see [[Main_game_logic:_yourgamename.game.php#Accessing_player_information]]
;Table.getPlayerNoById
:get 'player_no' (number) by id, see [[Main_game_logic:_yourgamename.game.php#Accessing_player_information]]
;Table.isCurrentPlayerZombie
;Table.getPlayerCount
:@deprecated, use getPlayersNumber,
;Table.createNextPlayerTable
:Return linked table of player order using passed parameter, see [[Main_game_logic:_yourgamename.game.php#Players turn order]]
;Table.getNextPlayerTable
:Return linked table of player order using natural players order, see [[Main_game_logic:_yourgamename.game.php#Players turn order]]
;Table.createPrevPlayerTable
:do not use
;Table.getPrevPlayerTable
:Return linked table of player order using natural players order reversed, see [[Main_game_logic:_yourgamename.game.php#Players turn order]]
;Table.getPlayerAfter
:get player after, see [[Main_game_logic:_yourgamename.game.php#Players turn order]]
;Table.getPlayerBefore
:get player before, see [[Main_game_logic:_yourgamename.game.php#Players turn order]]
;Table.activeNextPlayer
:Make the next player active in the natural player orde, see [[Main_game_logic:_yourgamename.game.php#Game states and active players]]
;Table.activePrevPlayer
:Make the prev player active in the natural player orde, see [[Main_game_logic:_yourgamename.game.php#Game states and active players]]
;Table.forceEndOfGame
:force to abandon game, normally its called when all players agree, but can be called to force people out when testing alpha or beta games and don't want to deal with update db and such (<code>$this->forceEndOfGame( $reason )</code>)
;Table.giveExtraTime
:give extra time to a player, usually when turn require multiple player states, see [[Main_game_logic:_yourgamename.game.php#Reflexion_time]]
;Table.checkZombieTurn
;Table.skipPlayersOutOfTime
:this is called by framework, do not use
;Table.onPlayerHasBeenZombified
:called when some player has been zombified because he quits the game (or have been "skipped"), unlikely you need to override this method, if you do you have to take into account first player quit vs any other player quit, you must call super implementation in any case if you decide to override it
;Table.forceAbandon
:it may be possible for force to abandon game in some cases, for example in alpha games when new database schema requires update and you did not code this (because for alpha its waste of time)
;Table.zombieBack
;Table.aiPlayer
;Table.aiNotPlaying
;Table.aiError
;Table.say
:this function processes chat message, do not use for game purposes, for word games use dedicated control
;Table.getGameProgression
:part of template, override to return proper data, see [[Main_game_logic:_yourgamename.game.php]] and [[Your_game_state_machine:_states.inc.php]]
;Table.getStatTypesForGame static
;Table.getStatTypes
:get the $stats_type array defined in stats.inc.php
;Table.stat_type_id_to_name
;Table.initStat
:initialize statistic https://en.doc.boardgamearena.com/Main_game_logic:_yourgamename.game.php#Game_statistics
;Table.getStat
:get statistic https://en.doc.boardgamearena.com/Main_game_logic:_yourgamename.game.php#Game_statistics
;Table.setStat
:set statistic https://en.doc.boardgamearena.com/Main_game_logic:_yourgamename.game.php#Game_statistics
;Table.setStatForAllPlayers
:set player statistics for all players, not document, does not check params, have some bad side effects
;Table.incStat
:inc statistic https://en.doc.boardgamearena.com/Main_game_logic:_yourgamename.game.php#Game_statistics
;Table.getStatFromResult
:helper function, do not use, should have been private for table class
;Table.setStatOnResult
:helper function, do not use, should have been private for table class
;Table.setStatOnResultForPlayer
:helper function, do not use, should have been private for table class
;Table.getStandardGameResultObject
:helper function, do not use, should have been private for table class
;Table.getGameRankInfos
;Table.argGameEnd
:framework end game function, do not call or override
;Table.stGameEnd
:framework end game function, do not call or override
;Table.stTutorialStart
;Table.isSoloGame
:return true if game is 1 player game or all other players are AI
;Table.notifyAllPlayers
:notification function, see https://en.doc.boardgamearena.com/Main_game_logic:_yourgamename.game.php
;Table.notifyPlayer
:notification function, see https://en.doc.boardgamearena.com/Main_game_logic:_yourgamename.game.php
;Table.onEndAjaxAction
:can be overriden to be executed before end of ajax action, unclear why would anybody need that
;Table.checkReturnState
:framework internal check action, do not call or override
;Table.sendNotifications
:framework internal function, do not call or override
;Table.getCurrentNotificationNextNo
;Table.getNotificationHistory
;Table.debugChat
:studio only - execute php code from chat, overriding won't work as it is called statically from table class
;Table.timeout
:studio only - can call from chat console to zombify current player
;Table.eliminatePlayer
:eliminate player, https://en.doc.boardgamearena.com/Main_game_logic:_yourgamename.game.php
;Table.isAsync
:return true if game is turn based, false if realtime, undocumented (why?)
;Table.getTimeLimits static
:internal framework function, do not call or override
;Table.getAsyncTimeLimits
:return time limits for turn based games
;Table.checkAsyncActivePlayersChange
:framework internal check action, do not call or override
;Table.upgradeTableDb
:override to perform db upgrade, see game template, also some notes in https://en.doc.boardgamearena.com/Post-release_phase
;Table.getReplayPoints
;Table.saveReplayPoint
;Table.undoAndReplayInit
;Table.removeAutoIncrementFromTable
:@deprecated
;Table.getFieldsListOfTable
:do not use or override, framework internal method to return columns of table
;Table.undoInit
;Table.undoSavepoint
:Instruction to save database state after current transaction is complete [[Main game logic: yourgamename.game.php#Undo moves]]
;Table.doUndoSavePoint
:do not call directly
;Table.undoRestorePoint
:Restore database from save point [[Main game logic: yourgamename.game.php#Undo moves]]
;Table.showTutorial
:do not call directly
;Table.seenTutorial
:do not call directly
;Table.activeTutorial
:do not call directly
;Table.forceGameTournamendEnd
:do not call directly
;Table.showCursor
;Table.showCursorClick
:undocumented, probably to share the cursor for demo/training
;Table.storeLegacyData
:API for campain games see [[Main game logic: yourgamename.game.php#Legacy games API]]
;Table.storeLegacyTeamData
:API for campain games see [[Main game logic: yourgamename.game.php#Legacy games API]]
;Table.retrieveLegacyData
:API for campain games see [[Main game logic: yourgamename.game.php#Legacy games API]]
;Table.retrieveLegacyTeamData
:API for campain games see [[Main game logic: yourgamename.game.php#Legacy games API]]
;Table.removeLegacyData
:API for campain games see [[Main game logic: yourgamename.game.php#Legacy games API]]
;Table.removeLegacyTeamData
:API for campain games see [[Main game logic: yourgamename.game.php#Legacy games API]]

== Methods in the APP_GameClass class ==
;APP_GameClass.getNewUnique
;APP_GameClass.getNew
;APP_GameClass.notifyNow

== Methods in the APP_DbObject class ==

;APP_DbObject.ConnectDb static
;APP_DbObject.DbQuery static
:main query method, see https://en.doc.boardgamearena.com/Main_game_logic:_yourgamename.game.php#Accessing_the_database
;APP_DbObject.DbTraceTimeBefore static
;APP_DbObject.DbTraceTimeAfter static
;APP_DbObject.DbGetLastId static
;APP_DbObject.DbDumpQueryHistory static
;APP_DbObject.DbAffectedRow static
;APP_DbObject.DbStartTransaction static
;APP_DbObject.DbCommit static
;APP_DbObject.DbRollback static
;APP_DbObject.DbRestartTransaction static
;APP_DbObject.DbSelect static
;APP_DbObject.CommitAllAndRestart static
;APP_DbObject.setDeadlockMode
;APP_DbObject.isDeadlockModeRetry
;APP_DbObject.enableMultiQueries
;APP_DbObject.sendMultiQueries
;APP_DbObject.escapeStringForDB
;APP_DbObject.getCollectionFromDB
:see https://en.doc.boardgamearena.com/Main_game_logic:_yourgamename.game.php#Accessing_the_database
;APP_DbObject.getNonEmptyCollectionFromDB
;APP_DbObject.getDoubleKeyCollectionFromDB
:see https://en.doc.boardgamearena.com/Main_game_logic:_yourgamename.game.php#Accessing_the_database
;APP_DbObject.getUniqueValueFromDB
;APP_DbObject.mysql_fetch_row
;APP_DbObject.mysql_fetch_assoc
;APP_DbObject.mysql_query
;APP_DbObject.getObjectFromDB
:see https://en.doc.boardgamearena.com/Main_game_logic:_yourgamename.game.php#Accessing_the_database
;APP_DbObject.getNonEmptyObjectFromDB
:see https://en.doc.boardgamearena.com/Main_game_logic:_yourgamename.game.php#Accessing_the_database
;APP_DbObject.getObjectListFromDB
:see https://en.doc.boardgamearena.com/Main_game_logic:_yourgamename.game.php#Accessing_the_database
;APP_DbObject.getSelectedDb static
;APP_DbObject.sqlParsing
;APP_DbObject.DbUsePrefix
;APP_DbObject.applyPrefix
;APP_DbObject.cache_store static
;APP_DbObject.cache_add static
;APP_DbObject.cache_exists static
;APP_DbObject.cache_fetch static
;APP_DbObject.cache_delete static
;APP_DbObject.cache_rollback static
;APP_DbObject.cache_commit static
;APP_DbObject.ensure_enough_time_since_last_action
;APP_DbObject.getMasterNodeDomain
;APP_DbObject.getMasterNodeUrl
;APP_DbObject.masterNodeRequest
;APP_DbObject.gameserverNodeRequest
;APP_DbObject.gameserverNodeRequestNoTable
;APP_DbObject.bgaCallUrl

== Methods in the APP_Object class ==
;APP_Object.watch
:@deprecated, do not use (noop)
;APP_Object.debug
:see https://en.doc.boardgamearena.com/Practical_debugging
;APP_Object.trace
:see https://en.doc.boardgamearena.com/Practical_debugging
;APP_Object.warn
:see https://en.doc.boardgamearena.com/Practical_debugging
;APP_Object.error
:see https://en.doc.boardgamearena.com/Practical_debugging
;APP_Object.dump
:see https://en.doc.boardgamearena.com/Practical_debugging
== Selected static methods in utility modules ==
;bga_rand
:recommended for randomness (dice rolls, etc), see [[Main game logic: yourgamename.game.php#About random and randomness]]
;shuffle_with_keys
:shuffle array with keys (basically shuffle keys and keep linked values), it shuffle argument, does not return anything
;totranslate
:returns its argument, used for MARKING of string for server strings https://en.doc.boardgamearena.com/Translations
;clienttranslate
:returns its argument, used for MARKING of string for client strings https://en.doc.boardgamearena.com/Translations
;_
:this is not the same as self::_, it is also translation function but only can translate mainsite strings, do not use in game code

[[Category:Studio]]

Tutorial reversi

2024-09-29T09:04:48Z

Sguzzer Gunayer: /* The rules */

'''Check out an updated version''' of the [[BGA Type Safe Template: Reversi|Reversi Tutorial]] which uses the [[BGA Type Safe Template]]. {{Studio_Framework_Navigation}}

== Introduction ==

Using this tutorial, you can build a complete working game on the BGA environment: Reversi.

Before you read this tutorial, you must:
* Read the overall presentations of the BGA Framework ([[Studio|see here]]).
* Know the [http://en.wikipedia.org/wiki/Reversi#Rules rules of Reversi].
* Know the languages used on BGA: PHP, SQL, HTML, CSS, Javascript
* '''Setup your development environment''' [http://en.doc.boardgamearena.com/First_steps_with_BGA_Studio First Steps with BGA Studio]

== Create your first game ==

''Note: you should already have created a project following instructions in [[First_steps_with_BGA_Studio#Create_a_new_game_project|Create a new game project]]. While you will find a '''reversi''' directory in your SFTP folder, do not use it for this tutorial. Instead, use the project you have created as an (empty) starting point.''

With the initial skeleton of code provided in your project, you can already start a game from the BGA Studio:
* Go to your [https://studio.boardgamearena.com/controlpanel studio Control panel], then Manage games and select your initial project. ''Note: there are warnings displayed about a missing BGG_ID and presentation text. You can ignore that for now.''
* Click the Play link next to your project name. This will open the Play page and offer to create a new table for your project. ''Optional: click the Heart icon to add your project to your favorite games list.''
* On the Play page, on the top of the page, make sure that your settings are "Simple game", "Real time" and "Manual".
* Click "Create table" to create a table of your project.
* For now, we are going to work with one player only, so use the (-) button to set the number of players to 1. Most of the time it is simpler to proceed with only one player during the early phase of development of your game, as it's easy and fast to start/stop games. If you choose to start with 2 players, you should see two names on the right: testdude0 and testdude1. To switch between them, press the red arrow button near their names; it will open another tab. This way you don't need to login and logout from multiple accounts.)
* Reminder: Always use the "Express Start" button to start the game.

Thus, you can start a "Reversi" game, and arrive on a void, empty game. Yeah.

End the game by clicking on the game options icon on the top right, and then on "Express Stop".

== Editing the game information (Optional) ==

This step is optional and will fix the warnings on the project page (missing BGG_ID and presentation).

==== Edits to fix Errors ====
* Edit your local copy of the <code>gameinfos.inc.php</code> file:
** Change the <code>bgg_id</code> value from <code>0</code> to <code>2389</code> - that's around line 37.
** Add <code>1,</code> to the players array - that's around line 41.
** Change the presentation array content - that's around line 134. Uncomment one line and change the text. Remove the final comma if you keep only one line!
* Upload the <code>gameinfos.inc.php</code> file to the SFTP server (see [[First_steps_with_BGA_Studio#Connect_to_your_SFTP_folder|Connect to your SFTP folder]]).

==== Test your Edits ====
* Go back to your project page, and in the "Game Information" section, click "Reload game informations".
* Finally, refresh the project page in your browser (usually CTRL-F5).

===== Not working? =====
Some changes will require bypassing the cache. It is often worth doing a hard refresh to make sure the

Sometimes the cache will keep your changes from showing. Since this is a possibility, it will be useful to know how to bypass the cache. To do so you may manually clear cache or use a shortcut to refresh and ignore the cached version of the page. Here's how

====== Windows ======
Chrome, Firefox, or Edge: Press <code>Ctrl+F5</code> or <code>Shift+F5</code> or <code>Ctrl+Shift+R</code>

====== Mac ======
Chrome or Firefox: Press <code>Shift+Command+R</code>

Safari for Mac: Press <code>Command+Option+E</code> to empty the cache, then hold down Shift and click Reload in the toolbar

== Make it look like Reversi ==

Let's start with the board. This will give you a good idea of how things will look and where tokens should go.

Be careful designing the layout of your game: you must always keep in mind that players with a 1024px screen width must be able to play. Usually, it means that the width of the play area can be 750px (in the worst case).

For Reversi, it's useless to have a 750x750px board - much too big, so we chose this one which fit perfectly (536x528):

[[File:Board.jpg]]

Note that we are using a jpg file. Jpg files are lighter than png, so they are faster to load. Later, we are going to use PNGs for tokens because they allow for transparency.

==== Add the board ====
use lowercase file names
* upload <code>board.jpg</code> in your <code>img/</code> directory.
* edit <code>reversi_reversi.tpl</code> to add a <code>div</code> for your board.

Note: If you are building this game by following the tutorial, you will have a different project name than <code>reversi</code> (i.e. <code>mygame_mygame.tpl</code>). The file names in your project will be different than shown in this tutorial, replacing <code>reversi</code> with your project name. Be sure that any code (other than comments) that references <code>reversi</code> is changed to your actual project name.

<pre>
<div id="board">
</div>
</pre>

* edit your <code>reversi.css</code> file to transform it into a visible board:

#board {
width: 536px;
height: 528px;
background-image: url('img/board.jpg');
}

'''Important: refresh your page.''' Here's your board:[[File:reversi1.jpg]]

If the board does not appear, refresh the page (always do this when you update the CSS file), and check the image filename. Remember file names are case sensitive!

==== Code the Grid ====
Now, we need to create some invisible HTML elements where squares are. These elements will be used as position references for the white and black tokens.

===== Build the grid of squares =====
The board is 8 squares by 8 squares. This means we need 64 squares. To avoid writing 64 individual <code>div</code> elements on our template, we are going to generate the squares on JS <code>setup</code>.

We'll do this in our Javascript <code>setup</code> method under <code>// TODO: Set up your game interface here, according to "gamedatas"</code>.

<pre>
const board = document.getElementById('board');
const hor_scale = 64.8;
const ver_scale = 64.4;
for (let x=1; x<=8; x++) {
for (let y=1; y<=8; y++) {
const left = Math.round((x - 1) * hor_scale + 10);
const top = Math.round((y - 1) * ver_scale + 7);
// we use afterbegin to make sure squares are placed before discs
board.insertAdjacentHTML(`afterbegin`, `<div id="square_${x}_${y}" class="square" style="left: ${left}px; top: ${top}px;"></div>`);
}
}
</pre>

Note: as you can see, squares in our <code>board.jpg</code> files do not have an exact width/height in pixels, and that's the reason we are using floating point numbers here.

===== Style Those Squares =====
Now, to finish our work and check if everything works fine, we are going to style our square a little bit in our CSS stylesheet:

<pre>
#board {
width: 536px;
height: 528px;
background-image: url('img/board.jpg');
position: relative;
}

.square {
width: 62px;
height: 62px;
position: absolute;
background-color: red;
}
</pre>

Explanations:
* With "<code>position: relative</code>" on board, we ensure square elements are positioned relatively to board.
* <code>background-color: red;</code> is used for testing. This allows us to see the invisible elements. (You could instead do something like <code>outline: 2px solid orange;</code> have fun and be creative)

Let's refresh and check our (beautiful) squares:

[[File:reversi2.jpg]]

Now that you know the squares are there, you can remove the test line <code>background-color: red;</code> from your <code>.square</code> class in the CSS stylesheet.

===== Not Working? =====
If the styled squares do not appear, inspect and check your css (Chrome DevTools: Application > Frames > top > Stylesheets > reversi.css).

== The Tokens ==

Now, our board is ready for some tokens!

[Note: Throughout this tutorial, sometimes "tokens" is used, and sometimes "discs" is used. They are often swapped if you're looking at code in the reversi example project.]

=== Build the Token ===
There are quite a few steps before the tokens will appear. You may be used to testing after every change, but that won't work well here. The token will '''not''' show until you have add styles to the css, js template to the tpl, utility method in the js, adjusted the php file, and added the token to the board in the js file.

==== HTML in the .tpl file ====
At first, we introduce a new 'div' element as a child of "board" to host all these tokens (in our template):

<pre>
<div id="board">

<div id="discs">
</div>
</div>
</pre>

Note: <code>discs</code> is plural. This div will be used to hold the token divs. Shortly, we will use javascript to add individual tokens to the board.

==== Add Token to img directory ====
Here's a new piece of art with the tokens. We need transparency here so we are using a png file:

[[File:tokens.png]]

Upload this image file <code>tokens.png</code> in your <code>img/</code> directory.

Important Fun Fact: we are using ONE file for both tokens. It is really important to use a minimum number of graphic files for your game. This is called the "CSS sprite" technique, because it makes the game load faster and more reliable. [http://www.w3schools.com/css/css_image_sprites.asp Read more about CSS sprites].

==== Style the Tokens in .css file ====
<pre>
.disc {
width: 56px;
height: 56px;
position: absolute;
background-image: url('img/tokens.png');
background-size: auto 100%;
}
.disc[data-color="ffffff"] { background-position-x: 0%; }
.disc[data-color="000000"] { background-position-x: 100%; }
</pre>

With this CSS code, we can set and change the token color by changing the <code>data-color</code> attribute. Using data instead of a class ensures it can be only one of them (the disc cannot be black and white at the same time).

Note the "<code>position: absolute</code>" which allows us to position tokens on the board and make them "slide" to their positions.

==== Add Token Utility Method in .js file ====
Now, let's make the first token appear on our board. Tokens are not visible at the beginning of the game: they appear dynamically during the game. For this reason, we are going to make them appear from our Javascript code, using a template string

Let's create a method in our Javascript code (in the <code>reversi.js</code> file) that will make a token appear on the board, using this template. Add under the section <code>//// Utility methods</code>:

<pre>
addDiscOnBoard: function( x, y, player )
{
var color = this.gamedatas.players[ player ].color;

document.getElementById('discs').insertAdjacentHTML('beforeend', `<div class="disc" data-color="${color}" id="disc_${x}${y}"></div>`);

this.placeOnObject( `disc_${x}${y}`, 'overall_player_board_'+player );
this.slideToObject( `disc_${x}${y}`, 'square_'+x+'_'+y ).play();
},
</pre>

===== Utility Method Explanation =====
* with <code>element.insertAdjacentHTML</code> method, we create a HTML piece of code and insert it as a new child of <code>tokens</code> div element.
* with <code>this.placeOnObject</code> BGA method, we place this element over the panel of some player.
* Immediately after, using <code>this.slideToObject</code> BGA method, we make the token slide to the <code>square</code> element, its final destination.
* <code>'overall_player_board_'+player</code> refers to the div element that contains each player's information and avatar. By initially placing the token here, it gives the effect that the player's avatar is throwing the token onto the board.

Note: don't forget to call the <code>play()</code>, otherwise the token will remain at its original location.

Note: during this process, the parent of the new token HTML element will stay <code>tokens</code>. <code>placeOnObject</code> and <code>slideToObject</code> methods are ''only'' moving the position of elements on screen, and they are ''not'' modifying the HTML tree.

==== Set Token Colors in setupNewGame in .game.php file ====
Before we can show a token, we need to set the player colors in the <code>setupNewGame</code> function in <code>reversi.game.php</code>:

Replace <code>$default_colors = $gameinfos['player_colors'];</code> with the following line:
<pre>
$default_colors = array( "ffffff", "000000" );
</pre>

Note: A few lines below, you may have to remove the line <code>this->reattributeColorsBasedOnPreferences( $players, $gameinfos['player_colors'] );</code>

=== Test the Token ===
Now, to test if everything works fine

==== <code>addTokenOnBoard()</code> in .js file to Test ====
In <code>reversi.js</code>, in <code>setup: function</code>, under the code we added to generate the squares.
this.addDiscOnBoard( 2, 2, this.player_id );
Now restart the game.

A token should appear and slide immediately to its position, like this:

[[File:reversi3.jpg]]

== The database ==

We did most of the client-side programming, so let's have a look on the other side now. To design the database model of our game, you will need to access the database. You won't need to do anything in database UI, yet.

=== Accessing the Database ===
To access the database, start a game, then click "Go to game database" link at the bottom of our game, to access the database directly with a PhpMyAdmin instance.

After the first time you've access the database, you could skip opening a game and instead, go to https://studio.boardgamearena.com/db/ . Your PhpMyAdmin username/password is in your welcome email.

'''Note''': do not remove existing tables

=== Create Table in .sql file ===
Now, you are able to create the table(s) you need for your game, and report every SQL command used in your <code>dbmodel.sql</code> file.

The database model of Reversi is short: just one table with the squares of the board.

<pre>
CREATE TABLE IF NOT EXISTS `board` (
`board_x` smallint(5) unsigned NOT NULL,
`board_y` smallint(5) unsigned NOT NULL,
`board_player` int(10) unsigned DEFAULT NULL,
PRIMARY KEY (`board_x`,`board_y`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
</pre>

Add the above SQL to <code>dbmodel.sql</code>. Pay special attention to the backtick <code>`</code> character vs. the single quote <code>'</code> when working with SQL.

=== Test the Table ===
Now, a new database with a <code>board</code> table will be created each time we start a Reversi game. This is why after modifying our <code>dbmodel.sql</code> it's a good time to stop your current game & start a new game.

Start a new game and verify a table is created.

== Setup the initial game position ==

'''Note''': From now on, you must launch the game with '''two players''' to get two <code>player_id</code>s within the database. Otherwise, the game will crash.

The <code>setupNewGame</code> method of our <code>reversi.game.php</code> is called during initial setup. This initializes our data and places the starting tokens on the board. At the beginning of the game, there should be 4 tokens on the board.

=== Initialize the Board in .game.php file ===
Under <code>// TODO: setup the initial game situation here</code>, initialize the board<pre>
// Init the board
$sql = "INSERT INTO board (board_x,board_y,board_player) VALUES ";
$sql_values = array();
list( $blackplayer_id, $whiteplayer_id ) = array_keys( $players );
for( $x=1; $x<=8; $x++ )
{
for( $y=1; $y<=8; $y++ )
{
$token_value = "NULL";
if( ($x==4 && $y==4) || ($x==5 && $y==5) ) // Initial positions of white player
$token_value = "'$whiteplayer_id'";
else if( ($x==4 && $y==5) || ($x==5 && $y==4) ) // Initial positions of black player
$token_value = "'$blackplayer_id'";

$sql_values[] = "('$x','$y',$token_value)";
}
}
$sql .= implode( ',', $sql_values );
$this->DbQuery( $sql );
</pre>

==== Board Initialization Explanation ====

* We create one table entry for each square, with a <code>NULL</code> value which means "empty square"
* On 4 of the squares, we place an initial token.

After this, we set <code>activeNextPlayer</code> to make the first player active at the beginning of the game (this line is already present in the default code template).

If you didn't do it earlier, you need to remove the call to <code>this->reattributeColorsBasedOnPreferences()</code> in <code>SetupNewGame()</code>. If you don't, player color preferences will try (and fail) to override the two colors supported here.

=== Show the Initial Token Setup ===
Now, we need to make these tokens appear on the client side. The first step is to return the token positions with our <code>getAllDatas()</code> PHP method. <code>getAllDatas()</code> is called during each page reload.

In the <code>getAllDatas()</code> method, after <code>// TODO: Gather all information about current game situation (visible by player $current_player_id)</code>, add the following lines:

<pre>
// Get reversi board token
$result['board'] = self::getObjectListFromDB( "SELECT board_x x, board_y y, board_player player
FROM board
WHERE board_player IS NOT NULL" );
</pre>

Next, you may need to modify the query that gets player information to also get the player's colors. This is in the variable <code>$sql</code>, above the lines you just inserted in <code>getAllDatas()</code>. Below is what the line will look like. Notice how we've added <code>player_color color</code> to the sql query.

<pre>
$sql = "SELECT player_id id, player_score score, player_color color FROM player ";
</pre>

We are using the BGA framework's <code>getObjectListFromDB()</code> that formats the result of this SQL query in a PHP array with x, y and player attributes. We add it to the result associative array with the key <code>board</code>.

Last, we process this array client side. Let's place a token on the board for each array item. We'll do this in our Javascript <code>setup</code> method under the code we added to generate the squares.

This will result in a removal or edit of the previously added line <code>this.addDiscOnBoard(2, 2, this.player_id);</code>

<pre>
for( var i in gamedatas.board )
{
var square = gamedatas.board[i];

if( square.player !== null )
{
this.addDiscOnBoard( square.x, square.y, square.player );
}
}
</pre>

The <code>board</code> entry created in <code>getAllDatas()</code> is used here as <code>gamedatas.board</code>

=== Test the Game Start ===
Reload... and here we are:

[[File:reversi5.jpg]]

It starts to feel like Reversi here...

== The game state machine ==

Stop your game, again. You're about to start the core game logic.

You already read [http://www.slideshare.net/boardgamearena/bga-studio-focus-on-bga-game-state-machine Focus on BGA game state machine], so you know that this is the heart of your game logic. For reversi, it's relatively simple. Here's a diagram of our game state machine:

[[File:reversi6.jpg]]

=== Build your States ===
And here's our <code>states.inc.php</code>, according to this diagram:

<pre>
$machinestates = array(

ST_BGA_GAME_SETUP => array(
"name" => "gameSetup",
"description" => clienttranslate("Game setup"),
"type" => "manager",
"action" => "stGameSetup",
"transitions" => array( "" => ST_PLAYER_PLAY_DISC )
),

ST_PLAYER_PLAY_DISC => array(
"name" => "playerTurn",
"description" => clienttranslate('${actplayer} must play a disc'),
"descriptionmyturn" => clienttranslate('${you} must play a disc'),
"type" => "activeplayer",
"args" => "argPlayerTurn",
"possibleactions" => array( 'actPlayDisc' ),
"transitions" => array( "playDisc" => ST_NEXT_PLAYER, "zombiePass" => ST_NEXT_PLAYER )
),

ST_NEXT_PLAYER => array(
"name" => "nextPlayer",
"type" => "game",
"action" => "stNextPlayer",
"updateGameProgression" => true,
"transitions" => array( "nextTurn" => ST_PLAYER_PLAY_DISC, "cantPlay" => ST_NEXT_PLAYER, "endGame" => ST_END_GAME )
),

ST_END_GAME => array(
"name" => "gameEnd",
"description" => clienttranslate("End of game"),
"type" => "manager",
"action" => "stGameEnd",
"args" => "argGameEnd"
)

);
</pre>

We used constants to give an index to the different states. This is to avoid mistakes when we reuse these indexes on the transitions array.

Let's create a file you'll put in <code>modules/php/constants.inc.php</code> :<pre>
<?php

/*
* State constants
*/
const ST_BGA_GAME_SETUP = 1;

const ST_PLAYER_PLAY_DISC = 10;
const ST_NEXT_PLAYER = 11;

const ST_END_GAME = 99;

?>
</pre>

You will also need to add <code>require_once("modules/php/constants.inc.php");</code> at the beginning of the state.inc.php to load these constants.

Now, in <code>reversi.game.php</code> let's create the methods that are declared in this game states description file:
* <code>argPlayerTurn</code>: referenced in the <code>args</code> property of the <code>playerTurn</code> state; this is the name of the method to call to retrieve arguments for this gamestate. Arguments are sent to the client side to be used on <code>onEnteringState</code> or to set arguments in the gamestate description.
* <code>stNextPlayer</code>: referenced in the <code>action</code> property of the <code>nextPlayer</code> state; this is the name of the method to call when this game state become the current game state.

=== Test Your States ===
... and start a new Reversi game.

As you can see on the screen capture below, the BGA framework makes the game jump to our first game state <code>playerTurn</code> right after the initial setup. That's why the status bar contains the description of <code>playerTurn</code> state ("XXXX must play a disc"):

[[File:reversi7.jpg]]

== The rules ==

We will use the <code>getPossibleMoves</code> PHP method to:
* Indicate to the current player where she is allowed to play by returning a list of coordinates
* Check if the player has the right to play in the spot they choose

<blockquote>
Example of <code>getPossibleMoves</code> here https://gist.github.com/leocaseiro/a8bc2851bd0caddd06685b5035937d15
</blockquote>

This is pure PHP programming here, and there are no special things from the BGA framework that can be used. This is why we won't go into details here. The overall idea is:
* Create a <code>getTurnedOverDiscs(x,y)</code> method that returns coordinates of discs that would be turned over if a token would be played at <code>x</code>,<code>y</code>.
* Loop through all free squares of the board and call the <code>getTurnedOverDiscs</code> method on each of them. If at least 1 token is turned over, this is a valid move.

IMPORTANT: Making a database query is slow! Please don't load the entire game board with a SQL query multiple times. In our implementation, we load the entire board once at the beginning of <code>getPossibleMoves</code>, and then pass the board as an argument to all methods.

If you want to look into details, please look at the "utility method" sections of <code>reversi.game.php</code>. If building the tutorial yourself, copy the functions under "Utility functions" comment from the Reversi tutorial.

== Display allowed moves ==

Now we want to highlight the squares where the player can place a disc.

To do this, we add a <code>argPlayerTurn</code> method in <code>reversi.game.php</code>. This method is called on the server each time we enter into <code>playerTurn</code> game state, and its result is transferred automatically to the client-side:

<pre>
function argPlayerTurn(): array
{
return [
'possibleMoves' => $this->getPossibleMoves( intval($this->getActivePlayerId()) )
];
}
</pre>

We use the <code>getPossibleMoves</code> method we just developed.

Each time we enter into a new game state, we use the <code>onEnteringState</code> Javascript method (in the <code>reversi.js</code> file, under "Game & client states"). This lets us use the data returned by the method above on the client side.

<pre>
onEnteringState: function( stateName, args )
{
console.log( 'Entering state: '+stateName );

switch( stateName )
{
case 'playerTurn':
this.updatePossibleMoves( args.args.possibleMoves );
break;
}
},
</pre>

So, when we enter into <code>playerTurn</code> game state, we call our <code>updatePossibleMoves</code> method (under the "Utility methods" section). This method looks like this:

<pre>
updatePossibleMoves: function( possibleMoves )
{
// Remove current possible moves
document.querySelectorAll('.possibleMove').forEach(div => div.classList.remove('possibleMove'));

for( var x in possibleMoves )
{
for( var y in possibleMoves[ x ] )
{
// x,y is a possible move
document.getElementById(`square_${x}_${y}`).classList.add('possibleMove');
}
}

this.addTooltipToClass( 'possibleMove', '', _('Place a disc here') );
},
</pre>
Here's what this does. At first, it removes all <code>possibleMove</code> classes currently applied with the very useful <code>document.querySelectorAll</code> method.

Then it loops through all possible moves our PHP <code>updatePossibleMoves</code> function created for us, and adds the <code>possibleMove</code> class to each corresponding square.

Finally, it uses the BGA framework <code>addTooltipToClass</code> method to associate a tooltip to all those highlighted squares so that players can understand their meaning.

To see the possible moves we need to create a CSS class (<code>possibleMove</code>) that can be applied to a <code>square</code> element to highlight it:
<pre>
.possibleMove {
background-color: white;
opacity: 0.2;
cursor: pointer;
}
</pre>

And here we are:

[[File:reversi8.jpg.jpg]]

== Let's play ==

From now, it's better to restart a game with 2 players, because we are going to implement a complete Reversi turn. The summary of what we are going to do is:
* When we click on a <code>possibleMove</code> square, send the move to the server.
* Server side, check the move is correct, apply Reversi rules and jump to next player.
* Client side, change the token position to reflect the move.

First we associate each click on a square to one of our methods using our Javascript <code>setup</code> method:

<pre>
document.querySelectorAll('.square').forEach(square => square.addEventListener('click', e => this.onPlayDisc(e)));
</pre>

Note the use of the "dojo.query" method to get all HTML elements with "square" class in just one function call. Now, our "onPlayDisc" method is called each time someone clicks on a square.

Here's our "onPlayDisc" method below:

<pre>
onPlayDisc: function( evt )
{
// Stop this event propagation
evt.preventDefault();
evt.stopPropagation();

// Get the cliqued square x and y
// Note: square id format is "square_X_Y"
var coords = evt.currentTarget.id.split('_');
var x = coords[1];
var y = coords[2];

if(!document.getElementById(`square_${x}_${y}`).classList.contains('possibleMove')) {
// This is not a possible move => the click does nothing
return ;
}

this.bgaPerformAction("actPlayDisc", {
x:x,
y:y
});
},
</pre>

What we do here is:
* We stop the propagation of the Javascript <code>onclick</code> event. Otherwise, it can lead to random behavior so it's always a good idea.
* We get the x/y coordinates of the square by using <code>evt.currentTarget.id</code>
* We check that clicked square has the <code>possibleMove</code> class, otherwise we know for sure that we can't play there.
* Finally, we make a call to the server using BGA <code>bgaPerformAction</code> method with argument x and y. This call will check that <code>actPlayDisc</code> action is possible, according to current game state (see <code>possibleactions</code> entry in our <code>playerTurn</code> game state defined above). This check is important to avoid issues if a player double clicks on a square.

Now, we have to manage this <code>actPlayDisc</code> action on the server side. Add a corresponding <code>actPlayDisc</code> method in our game logic (<code>reversi.game.php</code>):

<pre>
function actPlayDisc( int $x, int $y )
{
</pre>
(The function will be called when the front-side action is triggered using the Autowire mechanism, if you want to see how it works in details check https://en.doc.boardgamearena.com/Main_game_logic:_yourgamename.game.php#Actions_%28autowired%29 )
<pre>
$player_id = intval($this->getActivePlayerId());

// Now, check if this is a possible move
$board = $this->getBoard();
$turnedOverDiscs = $this->getTurnedOverDiscs( $x, $y, $player_id, $board );

if( count( $turnedOverDiscs ) > 0 )
{
// This move is possible!
</pre>

...now, we are using the <code>getTurnedOverDiscs</code> method again to check that this move is possible.

<pre>
// Let's place a disc at x,y and return all "$returned" discs to the active player

$sql = "UPDATE board SET board_player='$player_id'
WHERE ( board_x, board_y) IN ( ";

foreach( $turnedOverDiscs as $turnedOver )
{
$sql .= "('".$turnedOver['x']."','".$turnedOver['y']."'),";
}
$sql .= "('$x','$y') ) ";

$this->DbQuery( $sql );
</pre>

... we update the database to change the color of all turned over disc + the disc we just placed.

<pre>
// Update scores according to the number of disc on board
$sql = "UPDATE player
SET player_score = (
SELECT COUNT( board_x ) FROM board WHERE board_player=player_id
)";
$this->DbQuery( $sql );

// Statistics
$this->incStat( count( $turnedOverDiscs ), "turnedOver", $player_id );
if( ($x==1 && $y==1) || ($x==8 && $y==1) || ($x==1 && $y==8) || ($x==8 && $y==8) )
$this->incStat( 1, 'discPlayedOnCorner', $player_id );
else if( $x==1 || $x==8 || $y==1 || $y==8 )
$this->incStat( 1, 'discPlayedOnBorder', $player_id );
else if( $x>=3 && $x<=6 && $y>=3 && $y<=6 )
$this->incStat( 1, 'discPlayedOnCenter', $player_id );
</pre>

... now, we update both player score by counting all disc, and we manage game statistics.

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

$this->notifyAllPlayers( "turnOverDiscs", '', array(
'player_id' => $player_id,
'turnedOver' => $turnedOverDiscs
) );

$newScores = $this->getCollectionFromDb( "SELECT player_id, player_score FROM player", true );
$this->notifyAllPlayers( "newScores", "", array(
"scores" => $newScores
) );
</pre>

... then we notify about all these changes. We are using for that 3 notifications (<code>playDisc</code>, <code>turnOverDiscs</code> and <code>newScores</code> that we are going to implement on client side later). Note that the description of the <code>playDisc</code> notification will be logged in the game log.

<pre>
// Then, go to the next state
$this->gamestate->nextState( 'playDisc' );
}
else
throw new BgaSystemException( "Impossible move" );
}
</pre>

... finally, we jump to the next game state if everything goes fine (<code>playDisc</code> is the name of a transition in the <code>playerTurn</code> game state description above which leads to state 11 which is <code>nextPlayer</code>).

To make the statistics work, we have to initialize them in <code>stats.json</code>:

<pre>
{
"player": {
"discPlayedOnCorner": {
"id": 10,
"name": "Discs played on a corner",
"type": "int"
},
"discPlayedOnBorder": {
"id": 11,
"name": "Discs played on a border",
"type": "int"
},
"discPlayedOnCenter": {
"id": 12,
"name": "Discs played on board center part",
"type": "int"
},
"turnedOver": {
"id": 13,
"name": "Number of discs turned over",
"type": "int"
}
}
}
</pre>

A last thing to do on the server side is to activate the next player when we enter the <code>nextPlayer</code> game state (in the <code>reversi.game.php</code> file, under "Game state reactions"):

<pre>
function stNextPlayer(): void
{
// Active next player
$player_id = intval($this->activeNextPlayer());

// Check if both player has at least 1 discs, and if there are free squares to play
$player_to_discs = $this->getCollectionFromDb( "SELECT board_player, COUNT( board_x )
FROM board
GROUP BY board_player", true );

if( ! isset( $player_to_discs[ null ] ) )
{
// Index 0 has not been set => there's no more free place on the board !
// => end of the game
$this->gamestate->nextState( 'endGame' );
return ;
}
else if( ! isset( $player_to_discs[ $player_id ] ) )
{
// Active player has no more disc on the board => he looses immediately
$this->gamestate->nextState( 'endGame' );
return ;
}

// Can this player play?

$possibleMoves = $this->getPossibleMoves( $player_id );
if( count( $possibleMoves ) == 0 )
{

// This player can't play
// Can his opponent play ?
$opponent_id = (int)$this->getUniqueValueFromDb( "SELECT player_id FROM player WHERE player_id!='$player_id' " );
if( count( $this->getPossibleMoves( $opponent_id ) ) == 0 )
{
// Nobody can move => end of the game
$this->gamestate->nextState( 'endGame' );
}
else
{
// => pass his turn
$this->gamestate->nextState( 'cantPlay' );
}
}
else
{
// This player can play. Give him some extra time
$this->giveExtraTime( $player_id );
$this->gamestate->nextState( 'nextTurn' );
}
}
</pre>

Now, when we play a token, the rules are checked and the token appears in the database.

[[File:reversi9.jpg]]

Of course, as we don't manage notifications on client side, we need to press F5 after each move to see the changes on the board.

== Make the move appear automatically ==

Now, what we have to do is process the notifications sent by the server and make the move appear on the interface.

In our <code>setupNotifications</code> method in <code>reversi.js</code>, we register 2 methods for the 2 notifications we created at the previous step (<code>playDisc</code> and <code>turnOverDiscs</code>):

<pre>
const notifs = [
['playDisc', 500],
['turnOverDiscs', 1500],
['newScores', 1],
];

notifs.forEach((notif) => {
dojo.subscribe(notif[0], this, `notif_${notif[0]}`);
this.notifqueue.setSynchronous(notif[0], notif[1]);
});
</pre>

We will associate each of our 3 notifications with a method prefixed with <code>notif_</code>. We also define these notifications as "synchronous", with a duration in millisecond. It tells the user interface to wait some time after executing the notification, to let the animation end before starting the next notification. In our specific case, the animation will be the following:
* Make a disc slide from the player panel to its place on the board
* (wait 500ms)
* Make all turned over discs blink (and of course turned them over)
* (wait 1500ms)
* Update the player scores
* (no real delay on this one)

The second part of the code is a generic thing to automatically bind the notifs we configured to the <code>notif_<notifName></code> functions we are about to create.

Let's have a look now on the <code>playDisc</code> notification handler method:

<pre>
notif_playDisc: function( notif )
{
// Remove current possible moves (makes the board more clear)
document.querySelectorAll('.possibleMove').forEach(div => div.classList.remove('possibleMove'));

this.addDiscOnBoard( notif.args.x, notif.args.y, notif.args.player_id );
},
</pre>

No surprise here, we re-used some existing stuff to:
* Remove the highlighted squares.
* Add a new disc on board, coming from player panel.

Now, here's the method that handles the <code>turnOverDiscs</code> notification:

<pre>
notif_turnOverDiscs: function( notif )
{
// Get the color of the player who is returning the discs
var targetColor = this.gamedatas.players[ notif.args.player_id ].color;

// Made these discs blinking and set them to the specified color
for( var i in notif.args.turnedOver )
{
var disc = notif.args.turnedOver[ i ];

// Make the disc blink 2 times
var anim = dojo.fx.chain( [
dojo.fadeOut( { node: 'disc_'+disc.x+''+disc.y } ),
dojo.fadeIn( { node: 'disc_'+disc.x+''+disc.y } ),
dojo.fadeOut( {
node: 'disc_'+disc.x+''+disc.y,
onEnd: node => $(node).dataset.color = targetColor,
} ),
dojo.fadeIn( { node: 'disc_'+disc.x+''+disc.y } )

] ); // end of dojo.fx.chain

// ... and launch the animation
anim.play();
}
},
</pre>

The list of the discs to be turned over has been made available by our server side code in <code>notif.args.turnedOver</code> (see previous paragraph). We loop through all these discs, and create a complex animation using <code>dojo.Animation</code> for each of them. The complete documentation on dojo animations [http://dojotoolkit.org/documentation/tutorials/1.6/animation/ can be found here].

In few words: we create a chain of 4 animations to make the disc fade out, fade in, fade out again, and fade in again. At the end of the second fade out, we change the color of the disc. Finally, we launch the animation with <code>play()</code>.

And Also the notification to update the scores:

<pre>
notif_newScores: function( notif )
{
for( var player_id in notif.args.scores )
{
var newScore = notif.args.scores[ player_id ];
this.scoreCtrl[ player_id ].toValue( newScore );
}
},
</pre>

[[Category:Studio]]

Tutorial reversi

2024-09-29T08:54:45Z

Sguzzer Gunayer: /* Build the grid of squares */

'''Check out an updated version''' of the [[BGA Type Safe Template: Reversi|Reversi Tutorial]] which uses the [[BGA Type Safe Template]]. {{Studio_Framework_Navigation}}

== Introduction ==

Using this tutorial, you can build a complete working game on the BGA environment: Reversi.

Before you read this tutorial, you must:
* Read the overall presentations of the BGA Framework ([[Studio|see here]]).
* Know the [http://en.wikipedia.org/wiki/Reversi#Rules rules of Reversi].
* Know the languages used on BGA: PHP, SQL, HTML, CSS, Javascript
* '''Setup your development environment''' [http://en.doc.boardgamearena.com/First_steps_with_BGA_Studio First Steps with BGA Studio]

== Create your first game ==

''Note: you should already have created a project following instructions in [[First_steps_with_BGA_Studio#Create_a_new_game_project|Create a new game project]]. While you will find a '''reversi''' directory in your SFTP folder, do not use it for this tutorial. Instead, use the project you have created as an (empty) starting point.''

With the initial skeleton of code provided in your project, you can already start a game from the BGA Studio:
* Go to your [https://studio.boardgamearena.com/controlpanel studio Control panel], then Manage games and select your initial project. ''Note: there are warnings displayed about a missing BGG_ID and presentation text. You can ignore that for now.''
* Click the Play link next to your project name. This will open the Play page and offer to create a new table for your project. ''Optional: click the Heart icon to add your project to your favorite games list.''
* On the Play page, on the top of the page, make sure that your settings are "Simple game", "Real time" and "Manual".
* Click "Create table" to create a table of your project.
* For now, we are going to work with one player only, so use the (-) button to set the number of players to 1. Most of the time it is simpler to proceed with only one player during the early phase of development of your game, as it's easy and fast to start/stop games. If you choose to start with 2 players, you should see two names on the right: testdude0 and testdude1. To switch between them, press the red arrow button near their names; it will open another tab. This way you don't need to login and logout from multiple accounts.)
* Reminder: Always use the "Express Start" button to start the game.

Thus, you can start a "Reversi" game, and arrive on a void, empty game. Yeah.

End the game by clicking on the game options icon on the top right, and then on "Express Stop".

== Editing the game information (Optional) ==

This step is optional and will fix the warnings on the project page (missing BGG_ID and presentation).

==== Edits to fix Errors ====
* Edit your local copy of the <code>gameinfos.inc.php</code> file:
** Change the <code>bgg_id</code> value from <code>0</code> to <code>2389</code> - that's around line 37.
** Add <code>1,</code> to the players array - that's around line 41.
** Change the presentation array content - that's around line 134. Uncomment one line and change the text. Remove the final comma if you keep only one line!
* Upload the <code>gameinfos.inc.php</code> file to the SFTP server (see [[First_steps_with_BGA_Studio#Connect_to_your_SFTP_folder|Connect to your SFTP folder]]).

==== Test your Edits ====
* Go back to your project page, and in the "Game Information" section, click "Reload game informations".
* Finally, refresh the project page in your browser (usually CTRL-F5).

===== Not working? =====
Some changes will require bypassing the cache. It is often worth doing a hard refresh to make sure the

Sometimes the cache will keep your changes from showing. Since this is a possibility, it will be useful to know how to bypass the cache. To do so you may manually clear cache or use a shortcut to refresh and ignore the cached version of the page. Here's how

====== Windows ======
Chrome, Firefox, or Edge: Press <code>Ctrl+F5</code> or <code>Shift+F5</code> or <code>Ctrl+Shift+R</code>

====== Mac ======
Chrome or Firefox: Press <code>Shift+Command+R</code>

Safari for Mac: Press <code>Command+Option+E</code> to empty the cache, then hold down Shift and click Reload in the toolbar

== Make it look like Reversi ==

Let's start with the board. This will give you a good idea of how things will look and where tokens should go.

Be careful designing the layout of your game: you must always keep in mind that players with a 1024px screen width must be able to play. Usually, it means that the width of the play area can be 750px (in the worst case).

For Reversi, it's useless to have a 750x750px board - much too big, so we chose this one which fit perfectly (536x528):

[[File:Board.jpg]]

Note that we are using a jpg file. Jpg files are lighter than png, so they are faster to load. Later, we are going to use PNGs for tokens because they allow for transparency.

==== Add the board ====
use lowercase file names
* upload <code>board.jpg</code> in your <code>img/</code> directory.
* edit <code>reversi_reversi.tpl</code> to add a <code>div</code> for your board.

Note: If you are building this game by following the tutorial, you will have a different project name than <code>reversi</code> (i.e. <code>mygame_mygame.tpl</code>). The file names in your project will be different than shown in this tutorial, replacing <code>reversi</code> with your project name. Be sure that any code (other than comments) that references <code>reversi</code> is changed to your actual project name.

<pre>
<div id="board">
</div>
</pre>

* edit your <code>reversi.css</code> file to transform it into a visible board:

#board {
width: 536px;
height: 528px;
background-image: url('img/board.jpg');
}

'''Important: refresh your page.''' Here's your board:[[File:reversi1.jpg]]

If the board does not appear, refresh the page (always do this when you update the CSS file), and check the image filename. Remember file names are case sensitive!

==== Code the Grid ====
Now, we need to create some invisible HTML elements where squares are. These elements will be used as position references for the white and black tokens.

===== Build the grid of squares =====
The board is 8 squares by 8 squares. This means we need 64 squares. To avoid writing 64 individual <code>div</code> elements on our template, we are going to generate the squares on JS <code>setup</code>.

We'll do this in our Javascript <code>setup</code> method under <code>// TODO: Set up your game interface here, according to "gamedatas"</code>.

<pre>
const board = document.getElementById('board');
const hor_scale = 64.8;
const ver_scale = 64.4;
for (let x=1; x<=8; x++) {
for (let y=1; y<=8; y++) {
const left = Math.round((x - 1) * hor_scale + 10);
const top = Math.round((y - 1) * ver_scale + 7);
// we use afterbegin to make sure squares are placed before discs
board.insertAdjacentHTML(`afterbegin`, `<div id="square_${x}_${y}" class="square" style="left: ${left}px; top: ${top}px;"></div>`);
}
}
</pre>

Note: as you can see, squares in our <code>board.jpg</code> files do not have an exact width/height in pixels, and that's the reason we are using floating point numbers here.

===== Style Those Squares =====
Now, to finish our work and check if everything works fine, we are going to style our square a little bit in our CSS stylesheet:

<pre>
#board {
width: 536px;
height: 528px;
background-image: url('img/board.jpg');
position: relative;
}

.square {
width: 62px;
height: 62px;
position: absolute;
background-color: red;
}
</pre>

Explanations:
* With "<code>position: relative</code>" on board, we ensure square elements are positioned relatively to board.
* <code>background-color: red;</code> is used for testing. This allows us to see the invisible elements. (You could instead do something like <code>outline: 2px solid orange;</code> have fun and be creative)

Let's refresh and check our (beautiful) squares:

[[File:reversi2.jpg]]

Now that you know the squares are there, you can remove the test line <code>background-color: red;</code> from your <code>.square</code> class in the CSS stylesheet.

===== Not Working? =====
If the styled squares do not appear, inspect and check your css (Chrome DevTools: Application > Frames > top > Stylesheets > reversi.css).

== The Tokens ==

Now, our board is ready for some tokens!

[Note: Throughout this tutorial, sometimes "tokens" is used, and sometimes "discs" is used. They are often swapped if you're looking at code in the reversi example project.]

=== Build the Token ===
There are quite a few steps before the tokens will appear. You may be used to testing after every change, but that won't work well here. The token will '''not''' show until you have add styles to the css, js template to the tpl, utility method in the js, adjusted the php file, and added the token to the board in the js file.

==== HTML in the .tpl file ====
At first, we introduce a new 'div' element as a child of "board" to host all these tokens (in our template):

<pre>
<div id="board">

<div id="discs">
</div>
</div>
</pre>

Note: <code>discs</code> is plural. This div will be used to hold the token divs. Shortly, we will use javascript to add individual tokens to the board.

==== Add Token to img directory ====
Here's a new piece of art with the tokens. We need transparency here so we are using a png file:

[[File:tokens.png]]

Upload this image file <code>tokens.png</code> in your <code>img/</code> directory.

Important Fun Fact: we are using ONE file for both tokens. It is really important to use a minimum number of graphic files for your game. This is called the "CSS sprite" technique, because it makes the game load faster and more reliable. [http://www.w3schools.com/css/css_image_sprites.asp Read more about CSS sprites].

==== Style the Tokens in .css file ====
<pre>
.disc {
width: 56px;
height: 56px;
position: absolute;
background-image: url('img/tokens.png');
background-size: auto 100%;
}
.disc[data-color="ffffff"] { background-position-x: 0%; }
.disc[data-color="000000"] { background-position-x: 100%; }
</pre>

With this CSS code, we can set and change the token color by changing the <code>data-color</code> attribute. Using data instead of a class ensures it can be only one of them (the disc cannot be black and white at the same time).

Note the "<code>position: absolute</code>" which allows us to position tokens on the board and make them "slide" to their positions.

==== Add Token Utility Method in .js file ====
Now, let's make the first token appear on our board. Tokens are not visible at the beginning of the game: they appear dynamically during the game. For this reason, we are going to make them appear from our Javascript code, using a template string

Let's create a method in our Javascript code (in the <code>reversi.js</code> file) that will make a token appear on the board, using this template. Add under the section <code>//// Utility methods</code>:

<pre>
addDiscOnBoard: function( x, y, player )
{
var color = this.gamedatas.players[ player ].color;

document.getElementById('discs').insertAdjacentHTML('beforeend', `<div class="disc" data-color="${color}" id="disc_${x}${y}"></div>`);

this.placeOnObject( `disc_${x}${y}`, 'overall_player_board_'+player );
this.slideToObject( `disc_${x}${y}`, 'square_'+x+'_'+y ).play();
},
</pre>

===== Utility Method Explanation =====
* with <code>element.insertAdjacentHTML</code> method, we create a HTML piece of code and insert it as a new child of <code>tokens</code> div element.
* with <code>this.placeOnObject</code> BGA method, we place this element over the panel of some player.
* Immediately after, using <code>this.slideToObject</code> BGA method, we make the token slide to the <code>square</code> element, its final destination.
* <code>'overall_player_board_'+player</code> refers to the div element that contains each player's information and avatar. By initially placing the token here, it gives the effect that the player's avatar is throwing the token onto the board.

Note: don't forget to call the <code>play()</code>, otherwise the token will remain at its original location.

Note: during this process, the parent of the new token HTML element will stay <code>tokens</code>. <code>placeOnObject</code> and <code>slideToObject</code> methods are ''only'' moving the position of elements on screen, and they are ''not'' modifying the HTML tree.

==== Set Token Colors in setupNewGame in .game.php file ====
Before we can show a token, we need to set the player colors in the <code>setupNewGame</code> function in <code>reversi.game.php</code>:

Replace <code>$default_colors = $gameinfos['player_colors'];</code> with the following line:
<pre>
$default_colors = array( "ffffff", "000000" );
</pre>

Note: A few lines below, you may have to remove the line <code>this->reattributeColorsBasedOnPreferences( $players, $gameinfos['player_colors'] );</code>

=== Test the Token ===
Now, to test if everything works fine

==== <code>addTokenOnBoard()</code> in .js file to Test ====
In <code>reversi.js</code>, in <code>setup: function</code>, under the code we added to generate the squares.
this.addDiscOnBoard( 2, 2, this.player_id );
Now restart the game.

A token should appear and slide immediately to its position, like this:

[[File:reversi3.jpg]]

== The database ==

We did most of the client-side programming, so let's have a look on the other side now. To design the database model of our game, you will need to access the database. You won't need to do anything in database UI, yet.

=== Accessing the Database ===
To access the database, start a game, then click "Go to game database" link at the bottom of our game, to access the database directly with a PhpMyAdmin instance.

After the first time you've access the database, you could skip opening a game and instead, go to https://studio.boardgamearena.com/db/ . Your PhpMyAdmin username/password is in your welcome email.

'''Note''': do not remove existing tables

=== Create Table in .sql file ===
Now, you are able to create the table(s) you need for your game, and report every SQL command used in your <code>dbmodel.sql</code> file.

The database model of Reversi is short: just one table with the squares of the board.

<pre>
CREATE TABLE IF NOT EXISTS `board` (
`board_x` smallint(5) unsigned NOT NULL,
`board_y` smallint(5) unsigned NOT NULL,
`board_player` int(10) unsigned DEFAULT NULL,
PRIMARY KEY (`board_x`,`board_y`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
</pre>

Add the above SQL to <code>dbmodel.sql</code>. Pay special attention to the backtick <code>`</code> character vs. the single quote <code>'</code> when working with SQL.

=== Test the Table ===
Now, a new database with a <code>board</code> table will be created each time we start a Reversi game. This is why after modifying our <code>dbmodel.sql</code> it's a good time to stop your current game & start a new game.

Start a new game and verify a table is created.

== Setup the initial game position ==

'''Note''': From now on, you must launch the game with '''two players''' to get two <code>player_id</code>s within the database. Otherwise, the game will crash.

The <code>setupNewGame</code> method of our <code>reversi.game.php</code> is called during initial setup. This initializes our data and places the starting tokens on the board. At the beginning of the game, there should be 4 tokens on the board.

=== Initialize the Board in .game.php file ===
Under <code>// TODO: setup the initial game situation here</code>, initialize the board<pre>
// Init the board
$sql = "INSERT INTO board (board_x,board_y,board_player) VALUES ";
$sql_values = array();
list( $blackplayer_id, $whiteplayer_id ) = array_keys( $players );
for( $x=1; $x<=8; $x++ )
{
for( $y=1; $y<=8; $y++ )
{
$token_value = "NULL";
if( ($x==4 && $y==4) || ($x==5 && $y==5) ) // Initial positions of white player
$token_value = "'$whiteplayer_id'";
else if( ($x==4 && $y==5) || ($x==5 && $y==4) ) // Initial positions of black player
$token_value = "'$blackplayer_id'";

$sql_values[] = "('$x','$y',$token_value)";
}
}
$sql .= implode( ',', $sql_values );
$this->DbQuery( $sql );
</pre>

==== Board Initialization Explanation ====

* We create one table entry for each square, with a <code>NULL</code> value which means "empty square"
* On 4 of the squares, we place an initial token.

After this, we set <code>activeNextPlayer</code> to make the first player active at the beginning of the game (this line is already present in the default code template).

If you didn't do it earlier, you need to remove the call to <code>this->reattributeColorsBasedOnPreferences()</code> in <code>SetupNewGame()</code>. If you don't, player color preferences will try (and fail) to override the two colors supported here.

=== Show the Initial Token Setup ===
Now, we need to make these tokens appear on the client side. The first step is to return the token positions with our <code>getAllDatas()</code> PHP method. <code>getAllDatas()</code> is called during each page reload.

In the <code>getAllDatas()</code> method, after <code>// TODO: Gather all information about current game situation (visible by player $current_player_id)</code>, add the following lines:

<pre>
// Get reversi board token
$result['board'] = self::getObjectListFromDB( "SELECT board_x x, board_y y, board_player player
FROM board
WHERE board_player IS NOT NULL" );
</pre>

Next, you may need to modify the query that gets player information to also get the player's colors. This is in the variable <code>$sql</code>, above the lines you just inserted in <code>getAllDatas()</code>. Below is what the line will look like. Notice how we've added <code>player_color color</code> to the sql query.

<pre>
$sql = "SELECT player_id id, player_score score, player_color color FROM player ";
</pre>

We are using the BGA framework's <code>getObjectListFromDB()</code> that formats the result of this SQL query in a PHP array with x, y and player attributes. We add it to the result associative array with the key <code>board</code>.

Last, we process this array client side. Let's place a token on the board for each array item. We'll do this in our Javascript <code>setup</code> method under the code we added to generate the squares.

This will result in a removal or edit of the previously added line <code>this.addDiscOnBoard(2, 2, this.player_id);</code>

<pre>
for( var i in gamedatas.board )
{
var square = gamedatas.board[i];

if( square.player !== null )
{
this.addDiscOnBoard( square.x, square.y, square.player );
}
}
</pre>

The <code>board</code> entry created in <code>getAllDatas()</code> is used here as <code>gamedatas.board</code>

=== Test the Game Start ===
Reload... and here we are:

[[File:reversi5.jpg]]

It starts to feel like Reversi here...

== The game state machine ==

Stop your game, again. You're about to start the core game logic.

You already read [http://www.slideshare.net/boardgamearena/bga-studio-focus-on-bga-game-state-machine Focus on BGA game state machine], so you know that this is the heart of your game logic. For reversi, it's relatively simple. Here's a diagram of our game state machine:

[[File:reversi6.jpg]]

=== Build your States ===
And here's our <code>states.inc.php</code>, according to this diagram:

<pre>
$machinestates = array(

ST_BGA_GAME_SETUP => array(
"name" => "gameSetup",
"description" => clienttranslate("Game setup"),
"type" => "manager",
"action" => "stGameSetup",
"transitions" => array( "" => ST_PLAYER_PLAY_DISC )
),

ST_PLAYER_PLAY_DISC => array(
"name" => "playerTurn",
"description" => clienttranslate('${actplayer} must play a disc'),
"descriptionmyturn" => clienttranslate('${you} must play a disc'),
"type" => "activeplayer",
"args" => "argPlayerTurn",
"possibleactions" => array( 'actPlayDisc' ),
"transitions" => array( "playDisc" => ST_NEXT_PLAYER, "zombiePass" => ST_NEXT_PLAYER )
),

ST_NEXT_PLAYER => array(
"name" => "nextPlayer",
"type" => "game",
"action" => "stNextPlayer",
"updateGameProgression" => true,
"transitions" => array( "nextTurn" => ST_PLAYER_PLAY_DISC, "cantPlay" => ST_NEXT_PLAYER, "endGame" => ST_END_GAME )
),

ST_END_GAME => array(
"name" => "gameEnd",
"description" => clienttranslate("End of game"),
"type" => "manager",
"action" => "stGameEnd",
"args" => "argGameEnd"
)

);
</pre>

We used constants to give an index to the different states. This is to avoid mistakes when we reuse these indexes on the transitions array.

Let's create a file you'll put in <code>modules/php/constants.inc.php</code> :<pre>
<?php

/*
* State constants
*/
const ST_BGA_GAME_SETUP = 1;

const ST_PLAYER_PLAY_DISC = 10;
const ST_NEXT_PLAYER = 11;

const ST_END_GAME = 99;

?>
</pre>

You will also need to add <code>require_once("modules/php/constants.inc.php");</code> at the beginning of the state.inc.php to load these constants.

Now, in <code>reversi.game.php</code> let's create the methods that are declared in this game states description file:
* <code>argPlayerTurn</code>: referenced in the <code>args</code> property of the <code>playerTurn</code> state; this is the name of the method to call to retrieve arguments for this gamestate. Arguments are sent to the client side to be used on <code>onEnteringState</code> or to set arguments in the gamestate description.
* <code>stNextPlayer</code>: referenced in the <code>action</code> property of the <code>nextPlayer</code> state; this is the name of the method to call when this game state become the current game state.

=== Test Your States ===
... and start a new Reversi game.

As you can see on the screen capture below, the BGA framework makes the game jump to our first game state <code>playerTurn</code> right after the initial setup. That's why the status bar contains the description of <code>playerTurn</code> state ("XXXX must play a disc"):

[[File:reversi7.jpg]]

== The rules ==

We will use the <code>getPossibleMoves</code> PHP method to:
* Indicate to the current player where she is allowed to play by returning a list of coordinates
* Check if the player has the right to play in the spot they choose

<blockquote>
Example of getPossibleMoves here https://gist.github.com/leocaseiro/a8bc2851bd0caddd06685b5035937d15
</blockquote>

This is pure PHP programming here, and there are no special things from the BGA framework that can be used. This is why we won't go into details here. The overall idea is:
* Create a <code>getTurnedOverDiscs(x,y)</code> method that returns coordinates of discs that would be turned over if a token would be played at <code>x</code>,<code>y</code>.
* Loop through all free squares of the board and call the <code>getTurnedOverDiscs</code> method on each of them. If at least 1 token is turned over, this is a valid move.

IMPORTANT: Making a database query is slow! Please don't load the entire game board with a SQL query multiple times. In our implementation, we load the entire board once at the beginning of <code>getPossibleMoves</code>, and then pass the board as an argument to all methods.

If you want to look into details, please look at the "utility method" sections of <code>reversi.game.php</code>. If building the tutorial yourself, copy the functions under "Utility functions" comment from the Reversi tutorial.

== Display allowed moves ==

Now we want to highlight the squares where the player can place a disc.

To do this, we add a <code>argPlayerTurn</code> method in <code>reversi.game.php</code>. This method is called on the server each time we enter into <code>playerTurn</code> game state, and its result is transferred automatically to the client-side:

<pre>
function argPlayerTurn(): array
{
return [
'possibleMoves' => $this->getPossibleMoves( intval($this->getActivePlayerId()) )
];
}
</pre>

We use the <code>getPossibleMoves</code> method we just developed.

Each time we enter into a new game state, we use the <code>onEnteringState</code> Javascript method (in the <code>reversi.js</code> file, under "Game & client states"). This lets us use the data returned by the method above on the client side.

<pre>
onEnteringState: function( stateName, args )
{
console.log( 'Entering state: '+stateName );

switch( stateName )
{
case 'playerTurn':
this.updatePossibleMoves( args.args.possibleMoves );
break;
}
},
</pre>

So, when we enter into <code>playerTurn</code> game state, we call our <code>updatePossibleMoves</code> method (under the "Utility methods" section). This method looks like this:

<pre>
updatePossibleMoves: function( possibleMoves )
{
// Remove current possible moves
document.querySelectorAll('.possibleMove').forEach(div => div.classList.remove('possibleMove'));

for( var x in possibleMoves )
{
for( var y in possibleMoves[ x ] )
{
// x,y is a possible move
document.getElementById(`square_${x}_${y}`).classList.add('possibleMove');
}
}

this.addTooltipToClass( 'possibleMove', '', _('Place a disc here') );
},
</pre>
Here's what this does. At first, it removes all <code>possibleMove</code> classes currently applied with the very useful <code>document.querySelectorAll</code> method.

Then it loops through all possible moves our PHP <code>updatePossibleMoves</code> function created for us, and adds the <code>possibleMove</code> class to each corresponding square.

Finally, it uses the BGA framework <code>addTooltipToClass</code> method to associate a tooltip to all those highlighted squares so that players can understand their meaning.

To see the possible moves we need to create a CSS class (<code>possibleMove</code>) that can be applied to a <code>square</code> element to highlight it:
<pre>
.possibleMove {
background-color: white;
opacity: 0.2;
cursor: pointer;
}
</pre>

And here we are:

[[File:reversi8.jpg.jpg]]

== Let's play ==

From now, it's better to restart a game with 2 players, because we are going to implement a complete Reversi turn. The summary of what we are going to do is:
* When we click on a <code>possibleMove</code> square, send the move to the server.
* Server side, check the move is correct, apply Reversi rules and jump to next player.
* Client side, change the token position to reflect the move.

First we associate each click on a square to one of our methods using our Javascript <code>setup</code> method:

<pre>
document.querySelectorAll('.square').forEach(square => square.addEventListener('click', e => this.onPlayDisc(e)));
</pre>

Note the use of the "dojo.query" method to get all HTML elements with "square" class in just one function call. Now, our "onPlayDisc" method is called each time someone clicks on a square.

Here's our "onPlayDisc" method below:

<pre>
onPlayDisc: function( evt )
{
// Stop this event propagation
evt.preventDefault();
evt.stopPropagation();

// Get the cliqued square x and y
// Note: square id format is "square_X_Y"
var coords = evt.currentTarget.id.split('_');
var x = coords[1];
var y = coords[2];

if(!document.getElementById(`square_${x}_${y}`).classList.contains('possibleMove')) {
// This is not a possible move => the click does nothing
return ;
}

this.bgaPerformAction("actPlayDisc", {
x:x,
y:y
});
},
</pre>

What we do here is:
* We stop the propagation of the Javascript <code>onclick</code> event. Otherwise, it can lead to random behavior so it's always a good idea.
* We get the x/y coordinates of the square by using <code>evt.currentTarget.id</code>
* We check that clicked square has the <code>possibleMove</code> class, otherwise we know for sure that we can't play there.
* Finally, we make a call to the server using BGA <code>bgaPerformAction</code> method with argument x and y. This call will check that <code>actPlayDisc</code> action is possible, according to current game state (see <code>possibleactions</code> entry in our <code>playerTurn</code> game state defined above). This check is important to avoid issues if a player double clicks on a square.

Now, we have to manage this <code>actPlayDisc</code> action on the server side. Add a corresponding <code>actPlayDisc</code> method in our game logic (<code>reversi.game.php</code>):

<pre>
function actPlayDisc( int $x, int $y )
{
</pre>
(The function will be called when the front-side action is triggered using the Autowire mechanism, if you want to see how it works in details check https://en.doc.boardgamearena.com/Main_game_logic:_yourgamename.game.php#Actions_%28autowired%29 )
<pre>
$player_id = intval($this->getActivePlayerId());

// Now, check if this is a possible move
$board = $this->getBoard();
$turnedOverDiscs = $this->getTurnedOverDiscs( $x, $y, $player_id, $board );

if( count( $turnedOverDiscs ) > 0 )
{
// This move is possible!
</pre>

...now, we are using the <code>getTurnedOverDiscs</code> method again to check that this move is possible.

<pre>
// Let's place a disc at x,y and return all "$returned" discs to the active player

$sql = "UPDATE board SET board_player='$player_id'
WHERE ( board_x, board_y) IN ( ";

foreach( $turnedOverDiscs as $turnedOver )
{
$sql .= "('".$turnedOver['x']."','".$turnedOver['y']."'),";
}
$sql .= "('$x','$y') ) ";

$this->DbQuery( $sql );
</pre>

... we update the database to change the color of all turned over disc + the disc we just placed.

<pre>
// Update scores according to the number of disc on board
$sql = "UPDATE player
SET player_score = (
SELECT COUNT( board_x ) FROM board WHERE board_player=player_id
)";
$this->DbQuery( $sql );

// Statistics
$this->incStat( count( $turnedOverDiscs ), "turnedOver", $player_id );
if( ($x==1 && $y==1) || ($x==8 && $y==1) || ($x==1 && $y==8) || ($x==8 && $y==8) )
$this->incStat( 1, 'discPlayedOnCorner', $player_id );
else if( $x==1 || $x==8 || $y==1 || $y==8 )
$this->incStat( 1, 'discPlayedOnBorder', $player_id );
else if( $x>=3 && $x<=6 && $y>=3 && $y<=6 )
$this->incStat( 1, 'discPlayedOnCenter', $player_id );
</pre>

... now, we update both player score by counting all disc, and we manage game statistics.

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

$this->notifyAllPlayers( "turnOverDiscs", '', array(
'player_id' => $player_id,
'turnedOver' => $turnedOverDiscs
) );

$newScores = $this->getCollectionFromDb( "SELECT player_id, player_score FROM player", true );
$this->notifyAllPlayers( "newScores", "", array(
"scores" => $newScores
) );
</pre>

... then we notify about all these changes. We are using for that 3 notifications (<code>playDisc</code>, <code>turnOverDiscs</code> and <code>newScores</code> that we are going to implement on client side later). Note that the description of the <code>playDisc</code> notification will be logged in the game log.

<pre>
// Then, go to the next state
$this->gamestate->nextState( 'playDisc' );
}
else
throw new BgaSystemException( "Impossible move" );
}
</pre>

... finally, we jump to the next game state if everything goes fine (<code>playDisc</code> is the name of a transition in the <code>playerTurn</code> game state description above which leads to state 11 which is <code>nextPlayer</code>).

To make the statistics work, we have to initialize them in <code>stats.json</code>:

<pre>
{
"player": {
"discPlayedOnCorner": {
"id": 10,
"name": "Discs played on a corner",
"type": "int"
},
"discPlayedOnBorder": {
"id": 11,
"name": "Discs played on a border",
"type": "int"
},
"discPlayedOnCenter": {
"id": 12,
"name": "Discs played on board center part",
"type": "int"
},
"turnedOver": {
"id": 13,
"name": "Number of discs turned over",
"type": "int"
}
}
}
</pre>

A last thing to do on the server side is to activate the next player when we enter the <code>nextPlayer</code> game state (in the <code>reversi.game.php</code> file, under "Game state reactions"):

<pre>
function stNextPlayer(): void
{
// Active next player
$player_id = intval($this->activeNextPlayer());

// Check if both player has at least 1 discs, and if there are free squares to play
$player_to_discs = $this->getCollectionFromDb( "SELECT board_player, COUNT( board_x )
FROM board
GROUP BY board_player", true );

if( ! isset( $player_to_discs[ null ] ) )
{
// Index 0 has not been set => there's no more free place on the board !
// => end of the game
$this->gamestate->nextState( 'endGame' );
return ;
}
else if( ! isset( $player_to_discs[ $player_id ] ) )
{
// Active player has no more disc on the board => he looses immediately
$this->gamestate->nextState( 'endGame' );
return ;
}

// Can this player play?

$possibleMoves = $this->getPossibleMoves( $player_id );
if( count( $possibleMoves ) == 0 )
{

// This player can't play
// Can his opponent play ?
$opponent_id = (int)$this->getUniqueValueFromDb( "SELECT player_id FROM player WHERE player_id!='$player_id' " );
if( count( $this->getPossibleMoves( $opponent_id ) ) == 0 )
{
// Nobody can move => end of the game
$this->gamestate->nextState( 'endGame' );
}
else
{
// => pass his turn
$this->gamestate->nextState( 'cantPlay' );
}
}
else
{
// This player can play. Give him some extra time
$this->giveExtraTime( $player_id );
$this->gamestate->nextState( 'nextTurn' );
}
}
</pre>

Now, when we play a token, the rules are checked and the token appears in the database.

[[File:reversi9.jpg]]

Of course, as we don't manage notifications on client side, we need to press F5 after each move to see the changes on the board.

== Make the move appear automatically ==

Now, what we have to do is process the notifications sent by the server and make the move appear on the interface.

In our <code>setupNotifications</code> method in <code>reversi.js</code>, we register 2 methods for the 2 notifications we created at the previous step (<code>playDisc</code> and <code>turnOverDiscs</code>):

<pre>
const notifs = [
['playDisc', 500],
['turnOverDiscs', 1500],
['newScores', 1],
];

notifs.forEach((notif) => {
dojo.subscribe(notif[0], this, `notif_${notif[0]}`);
this.notifqueue.setSynchronous(notif[0], notif[1]);
});
</pre>

We will associate each of our 3 notifications with a method prefixed with <code>notif_</code>. We also define these notifications as "synchronous", with a duration in millisecond. It tells the user interface to wait some time after executing the notification, to let the animation end before starting the next notification. In our specific case, the animation will be the following:
* Make a disc slide from the player panel to its place on the board
* (wait 500ms)
* Make all turned over discs blink (and of course turned them over)
* (wait 1500ms)
* Update the player scores
* (no real delay on this one)

The second part of the code is a generic thing to automatically bind the notifs we configured to the <code>notif_<notifName></code> functions we are about to create.

Let's have a look now on the <code>playDisc</code> notification handler method:

<pre>
notif_playDisc: function( notif )
{
// Remove current possible moves (makes the board more clear)
document.querySelectorAll('.possibleMove').forEach(div => div.classList.remove('possibleMove'));

this.addDiscOnBoard( notif.args.x, notif.args.y, notif.args.player_id );
},
</pre>

No surprise here, we re-used some existing stuff to:
* Remove the highlighted squares.
* Add a new disc on board, coming from player panel.

Now, here's the method that handles the <code>turnOverDiscs</code> notification:

<pre>
notif_turnOverDiscs: function( notif )
{
// Get the color of the player who is returning the discs
var targetColor = this.gamedatas.players[ notif.args.player_id ].color;

// Made these discs blinking and set them to the specified color
for( var i in notif.args.turnedOver )
{
var disc = notif.args.turnedOver[ i ];

// Make the disc blink 2 times
var anim = dojo.fx.chain( [
dojo.fadeOut( { node: 'disc_'+disc.x+''+disc.y } ),
dojo.fadeIn( { node: 'disc_'+disc.x+''+disc.y } ),
dojo.fadeOut( {
node: 'disc_'+disc.x+''+disc.y,
onEnd: node => $(node).dataset.color = targetColor,
} ),
dojo.fadeIn( { node: 'disc_'+disc.x+''+disc.y } )

] ); // end of dojo.fx.chain

// ... and launch the animation
anim.play();
}
},
</pre>

The list of the discs to be turned over has been made available by our server side code in <code>notif.args.turnedOver</code> (see previous paragraph). We loop through all these discs, and create a complex animation using <code>dojo.Animation</code> for each of them. The complete documentation on dojo animations [http://dojotoolkit.org/documentation/tutorials/1.6/animation/ can be found here].

In few words: we create a chain of 4 animations to make the disc fade out, fade in, fade out again, and fade in again. At the end of the second fade out, we change the color of the disc. Finally, we launch the animation with <code>play()</code>.

And Also the notification to update the scores:

<pre>
notif_newScores: function( notif )
{
for( var player_id in notif.args.scores )
{
var newScore = notif.args.scores[ player_id ];
this.scoreCtrl[ player_id ].toValue( newScore );
}
},
</pre>

[[Category:Studio]]

Tutorial reversi

2024-09-29T08:34:06Z

Sguzzer Gunayer:

'''Check out an updated version''' of the [[BGA Type Safe Template: Reversi|Reversi Tutorial]] which uses the [[BGA Type Safe Template]]. {{Studio_Framework_Navigation}}

== Introduction ==

Using this tutorial, you can build a complete working game on the BGA environment: Reversi.

Before you read this tutorial, you must:
* Read the overall presentations of the BGA Framework ([[Studio|see here]]).
* Know the [http://en.wikipedia.org/wiki/Reversi#Rules rules of Reversi].
* Know the languages used on BGA: PHP, SQL, HTML, CSS, Javascript
* '''Setup your development environment''' [http://en.doc.boardgamearena.com/First_steps_with_BGA_Studio First Steps with BGA Studio]

== Create your first game ==

''Note: you should already have created a project following instructions in [[First_steps_with_BGA_Studio#Create_a_new_game_project|Create a new game project]]. While you will find a '''reversi''' directory in your SFTP folder, do not use it for this tutorial. Instead, use the project you have created as an (empty) starting point.''

With the initial skeleton of code provided in your project, you can already start a game from the BGA Studio:
* Go to your [https://studio.boardgamearena.com/controlpanel studio Control panel], then Manage games and select your initial project. ''Note: there are warnings displayed about a missing BGG_ID and presentation text. You can ignore that for now.''
* Click the Play link next to your project name. This will open the Play page and offer to create a new table for your project. ''Optional: click the Heart icon to add your project to your favorite games list.''
* On the Play page, on the top of the page, make sure that your settings are "Simple game", "Real time" and "Manual".
* Click "Create table" to create a table of your project.
* For now, we are going to work with one player only, so use the (-) button to set the number of players to 1. Most of the time it is simpler to proceed with only one player during the early phase of development of your game, as it's easy and fast to start/stop games. If you choose to start with 2 players, you should see two names on the right: testdude0 and testdude1. To switch between them, press the red arrow button near their names; it will open another tab. This way you don't need to login and logout from multiple accounts.)
* Reminder: Always use the "Express Start" button to start the game.

Thus, you can start a "Reversi" game, and arrive on a void, empty game. Yeah.

End the game by clicking on the game options icon on the top right, and then on "Express Stop".

== Editing the game information (Optional) ==

This step is optional and will fix the warnings on the project page (missing BGG_ID and presentation).

==== Edits to fix Errors ====
* Edit your local copy of the <code>gameinfos.inc.php</code> file:
** Change the <code>bgg_id</code> value from <code>0</code> to <code>2389</code> - that's around line 37.
** Add <code>1,</code> to the players array - that's around line 41.
** Change the presentation array content - that's around line 134. Uncomment one line and change the text. Remove the final comma if you keep only one line!
* Upload the <code>gameinfos.inc.php</code> file to the SFTP server (see [[First_steps_with_BGA_Studio#Connect_to_your_SFTP_folder|Connect to your SFTP folder]]).

==== Test your Edits ====
* Go back to your project page, and in the "Game Information" section, click "Reload game informations".
* Finally, refresh the project page in your browser (usually CTRL-F5).

===== Not working? =====
Some changes will require bypassing the cache. It is often worth doing a hard refresh to make sure the

Sometimes the cache will keep your changes from showing. Since this is a possibility, it will be useful to know how to bypass the cache. To do so you may manually clear cache or use a shortcut to refresh and ignore the cached version of the page. Here's how

====== Windows ======
Chrome, Firefox, or Edge: Press <code>Ctrl+F5</code> or <code>Shift+F5</code> or <code>Ctrl+Shift+R</code>

====== Mac ======
Chrome or Firefox: Press <code>Shift+Command+R</code>

Safari for Mac: Press <code>Command+Option+E</code> to empty the cache, then hold down Shift and click Reload in the toolbar

== Make it look like Reversi ==

Let's start with the board. This will give you a good idea of how things will look and where tokens should go.

Be careful designing the layout of your game: you must always keep in mind that players with a 1024px screen width must be able to play. Usually, it means that the width of the play area can be 750px (in the worst case).

For Reversi, it's useless to have a 750x750px board - much too big, so we chose this one which fit perfectly (536x528):

[[File:Board.jpg]]

Note that we are using a jpg file. Jpg files are lighter than png, so they are faster to load. Later, we are going to use PNGs for tokens because they allow for transparency.

==== Add the board ====
use lowercase file names
* upload <code>board.jpg</code> in your <code>img/</code> directory.
* edit <code>reversi_reversi.tpl</code> to add a <code>div</code> for your board.

Note: If you are building this game by following the tutorial, you will have a different project name than <code>reversi</code> (i.e. <code>mygame_mygame.tpl</code>). The file names in your project will be different than shown in this tutorial, replacing <code>reversi</code> with your project name. Be sure that any code (other than comments) that references <code>reversi</code> is changed to your actual project name.

<pre>
<div id="board">
</div>
</pre>

* edit your <code>reversi.css</code> file to transform it into a visible board:

#board {
width: 536px;
height: 528px;
background-image: url('img/board.jpg');
}

'''Important: refresh your page.''' Here's your board:[[File:reversi1.jpg]]

If the board does not appear, refresh the page (always do this when you update the CSS file), and check the image filename. Remember file names are case sensitive!

==== Code the Grid ====
Now, we need to create some invisible HTML elements where squares are. These elements will be used as position references for the white and black tokens.

===== Build the grid of squares =====
The board is 8 squares by 8 squares. This means we need 64 squares. To avoid writing 64 individual <code>div</code> elements on our template, we are going to generate the squares on JS setup.

We'll do this in our Javascript <code>setup</code> method under <code>// TODO: Set up your game interface here, according to "gamedatas"</code>.

<pre>
const board = document.getElementById('board');
const hor_scale = 64.8;
const ver_scale = 64.4;
for (let x=1; x<=8; x++) {
for (let y=1; y<=8; y++) {
const left = Math.round((x - 1) * hor_scale + 10);
const top = Math.round((y - 1) * ver_scale + 7);
// we use afterbegin to make sure squares are placed before discs
board.insertAdjacentHTML(`afterbegin`, `<div id="square_${x}_${y}" class="square" style="left: ${left}px; top: ${top}px;"></div>`);
}
}
</pre>

Note: as you can see, squares in our <code>board.jpg</code> files do not have an exact width/height in pixels, and that's the reason we are using floating point numbers here.

===== Style Those Squares =====
Now, to finish our work and check if everything works fine, we are going to style our square a little bit in our CSS stylesheet:

<pre>
#board {
width: 536px;
height: 528px;
background-image: url('img/board.jpg');
position: relative;
}

.square {
width: 62px;
height: 62px;
position: absolute;
background-color: red;
}
</pre>

Explanations:
* With "position: relative" on board, we ensure square elements are positioned relatively to board.
* <code>background-color: red;</code> is used for testing. This allows us to see the invisible elements. (You could instead do something like <code>outline: 2px solid orange;</code> have fun and be creative)

Let's refresh and check our (beautiful) squares:

[[File:reversi2.jpg]]

Now that you know the squares are there, you can remove the test line <code>background-color: red;</code> from your <code>.square</code> class in the CSS stylesheet.

===== Not Working? =====
If the styled squares do not appear, inspect and check your css (Chrome DevTools: Application > Frames > top > Stylesheets > reversi.css).

== The Tokens ==

Now, our board is ready for some tokens!

[Note: Throughout this tutorial, sometimes "tokens" is used, and sometimes "discs" is used. They are often swapped if you're looking at code in the reversi example project.]

=== Build the Token ===
There are quite a few steps before the tokens will appear. You may be used to testing after every change, but that won't work well here. The token will '''not''' show until you have add styles to the css, js template to the tpl, utility method in the js, adjusted the php file, and added the token to the board in the js file.

==== HTML in the .tpl file ====
At first, we introduce a new 'div' element as a child of "board" to host all these tokens (in our template):

<pre>
<div id="board">

<div id="discs">
</div>
</div>
</pre>

Note: <code>discs</code> is plural. This div will be used to hold the token divs. Shortly, we will use javascript to add individual tokens to the board.

==== Add Token to img directory ====
Here's a new piece of art with the tokens. We need transparency here so we are using a png file:

[[File:tokens.png]]

Upload this image file <code>tokens.png</code> in your <code>img/</code> directory.

Important Fun Fact: we are using ONE file for both tokens. It is really important to use a minimum number of graphic files for your game. This is called the "CSS sprite" technique, because it makes the game load faster and more reliable. [http://www.w3schools.com/css/css_image_sprites.asp Read more about CSS sprites].

==== Style the Tokens in .css file ====
<pre>
.disc {
width: 56px;
height: 56px;
position: absolute;
background-image: url('img/tokens.png');
background-size: auto 100%;
}
.disc[data-color="ffffff"] { background-position-x: 0%; }
.disc[data-color="000000"] { background-position-x: 100%; }
</pre>

With this CSS code, we can set and change the token color by changing the data-color attribute. Using data instead of a class ensures it can be only one of them (the disc cannot be black and white at the same time).

Note the "<code>position: absolute</code>" which allows us to position tokens on the board and make them "slide" to their positions.

==== Add Token Utility Method in .js file ====
Now, let's make the first token appear on our board. Tokens are not visible at the beginning of the game: they appear dynamically during the game. For this reason, we are going to make them appear from our Javascript code, using a template string

Let's create a method in our Javascript code (in the <code>reversi.js</code> file) that will make a token appear on the board, using this template. Add under the section //// Utility methods:

<pre>
addDiscOnBoard: function( x, y, player )
{
var color = this.gamedatas.players[ player ].color;

document.getElementById('discs').insertAdjacentHTML('beforeend', `<div class="disc" data-color="${color}" id="disc_${x}${y}"></div>`);

this.placeOnObject( `disc_${x}${y}`, 'overall_player_board_'+player );
this.slideToObject( `disc_${x}${y}`, 'square_'+x+'_'+y ).play();
},
</pre>

===== Utility Method Explanation =====
* with <code>element.insertAdjacentHTML</code> method, we create a HTML piece of code and insert it as a new child of <code>tokens</code> div element.
* with <code>this.placeOnObject</code> BGA method, we place this element over the panel of some player.
* Immediately after, using <code>this.slideToObject</code> BGA method, we make the token slide to the <code>square</code> element, its final destination.
* <code>'overall_player_board_'+player</code> refers to the div element that contains each player's information and avatar. By initially placing the token here, it gives the effect that the player's avatar is throwing the token onto the board.

Note: don't forget to call the <code>play()</code>, otherwise the token will remain at its original location.

Note: during this process, the parent of the new token HTML element will stay <code>tokens</code>. <code>placeOnObject</code> and <code>slideToObject</code> methods are ''only'' moving the position of elements on screen, and they are ''not'' modifying the HTML tree.

==== Set Token Colors in setupNewGame in .game.php file ====
Before we can show a token, we need to set the player colors in the <code>setupNewGame</code> function in <code>reversi.game.php</code>:

Replace <code>$default_colors = $gameinfos['player_colors'];</code> with the following line:
<pre>
$default_colors = array( "ffffff", "000000" );
</pre>

Note: A few lines below, you may have to remove the line <code>this->reattributeColorsBasedOnPreferences( $players, $gameinfos['player_colors'] );</code>

=== Test the Token ===
Now, to test if everything works fine

==== addTokenOnBoard() in .js file to Test ====
In <code>reversi.js</code>, in <code>setup: function</code>, under the code we added to generate the squares.
this.addDiscOnBoard( 2, 2, this.player_id );
Now restart the game.

A token should appear and slide immediately to its position, like this:

[[File:reversi3.jpg]]

== The database ==

We did most of the client-side programming, so let's have a look on the other side now. To design the database model of our game, you will need to access the database. You won't need to do anything in database UI, yet.

=== Accessing the Database ===
To access the database, start a game, then click "Go to game database" link at the bottom of our game, to access the database directly with a PhpMyAdmin instance.

After the first time you've acess the database, you could skip opening a game and instead, go to https://studio.boardgamearena.com/db/ . Your PhpMyAdmin username/password is in your welcome email.

'''Note''': do not remove existing tables

=== Create Table in .sql file ===
Now, you are able to create the table(s) you need for your game, and report every SQL command used in your <code>dbmodel.sql</code> file.

The database model of Reversi is short: just one table with the squares of the board.

<pre>
CREATE TABLE IF NOT EXISTS `board` (
`board_x` smallint(5) unsigned NOT NULL,
`board_y` smallint(5) unsigned NOT NULL,
`board_player` int(10) unsigned DEFAULT NULL,
PRIMARY KEY (`board_x`,`board_y`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
</pre>

Add the above SQL to <code>dbmodel.sql</code>. Pay special attention to the backtick <code>`</code> character vs. the single quote <code>'</code> when working with SQL.

=== Test the Table ===
Now, a new database with a <code>board</code> table will be created each time we start a Reversi game. This is why after modifying our <code>dbmodel.sql</code> it's a good time to stop your current game & start a new game.

Start a new game and verify a table is created.

== Setup the initial game position ==

'''Note''': From now on, you must launch the game with '''two players''' to get two <code>player_id</code>s within the database. Otherwise, the game will crash.

The <code>setupNewGame</code> method of our <code>reversi.game.php</code> is called during initial setup. This initializes our data and places the starting tokens on the board. At the beginning of the game, there should be 4 tokens on the board.

=== Initialize the Board in .game.php file ===
Under <code>// TODO: setup the initial game situation here</code>, initialize the board<pre>
// Init the board
$sql = "INSERT INTO board (board_x,board_y,board_player) VALUES ";
$sql_values = array();
list( $blackplayer_id, $whiteplayer_id ) = array_keys( $players );
for( $x=1; $x<=8; $x++ )
{
for( $y=1; $y<=8; $y++ )
{
$token_value = "NULL";
if( ($x==4 && $y==4) || ($x==5 && $y==5) ) // Initial positions of white player
$token_value = "'$whiteplayer_id'";
else if( ($x==4 && $y==5) || ($x==5 && $y==4) ) // Initial positions of black player
$token_value = "'$blackplayer_id'";

$sql_values[] = "('$x','$y',$token_value)";
}
}
$sql .= implode( ',', $sql_values );
$this->DbQuery( $sql );
</pre>

==== Board Initialization Explanation ====

* We create one table entry for each square, with a <code>NULL</code> value which means "empty square"
* On 4 of the squares, we place an initial token.

After this, we set <code>activeNextPlayer</code> to make the first player active at the beginning of the game (this line is already present in the default code template).

If you didn't do it earlier, you need to remove the call to <code>this->reattributeColorsBasedOnPreferences()</code> in <code>SetupNewGame()</code>. If you don't, player color preferences will try (and fail) to override the two colors supported here.

=== Show the Initial Token Setup ===
Now, we need to make these tokens appear on the client side. The first step is to return the token positions with our <code>getAllDatas()</code> PHP method. <code>getAllDatas()</code> is called during each page reload.

In the <code>getAllDatas()</code> method, after <code>// TODO: Gather all information about current game situation (visible by player $current_player_id)</code>, add the following lines:

<pre>
// Get reversi board token
$result['board'] = self::getObjectListFromDB( "SELECT board_x x, board_y y, board_player player
FROM board
WHERE board_player IS NOT NULL" );
</pre>

Next, you may need to modify the query that gets player information to also get the player's colors. This is in the variable <code>$sql</code>, above the lines you just inserted in <code>getAllDatas()</code>. Below is what the line will look like. Notice how we've added <code>player_color color</code> to the sql query.

<pre>
$sql = "SELECT player_id id, player_score score, player_color color FROM player ";
</pre>

We are using the BGA framework's <code>getObjectListFromDB()</code> that formats the result of this SQL query in a PHP array with x, y and player attributes. We add it to the result associative array with the key <code>board</code>.

Last, we process this array client side. Let's place a token on the board for each array item. We'll do this in our Javascript <code>setup</code> method under the code we added to generate the squares.

This will result in a removal or edit of the previously added line <code>this.addDiscOnBoard(2, 2, this.player_id);</code>

<pre>
for( var i in gamedatas.board )
{
var square = gamedatas.board[i];

if( square.player !== null )
{
this.addDiscOnBoard( square.x, square.y, square.player );
}
}
</pre>

The <code>board</code> entry created in <code>getAllDatas()</code> is used here as <code>gamedatas.board</code>

=== Test the Game Start ===
Reload... and here we are:

[[File:reversi5.jpg]]

It starts to feel like Reversi here...

== The game state machine ==

Stop your game, again. You're about to start the core game logic.

You already read [http://www.slideshare.net/boardgamearena/bga-studio-focus-on-bga-game-state-machine Focus on BGA game state machine], so you know that this is the heart of your game logic. For reversi, it's relatively simple. Here's a diagram of our game state machine:

[[File:reversi6.jpg]]

=== Build your States ===
And here's our <code>states.inc.php</code>, according to this diagram:

<pre>
$machinestates = array(

ST_BGA_GAME_SETUP => array(
"name" => "gameSetup",
"description" => clienttranslate("Game setup"),
"type" => "manager",
"action" => "stGameSetup",
"transitions" => array( "" => ST_PLAYER_PLAY_DISC )
),

ST_PLAYER_PLAY_DISC => array(
"name" => "playerTurn",
"description" => clienttranslate('${actplayer} must play a disc'),
"descriptionmyturn" => clienttranslate('${you} must play a disc'),
"type" => "activeplayer",
"args" => "argPlayerTurn",
"possibleactions" => array( 'actPlayDisc' ),
"transitions" => array( "playDisc" => ST_NEXT_PLAYER, "zombiePass" => ST_NEXT_PLAYER )
),

ST_NEXT_PLAYER => array(
"name" => "nextPlayer",
"type" => "game",
"action" => "stNextPlayer",
"updateGameProgression" => true,
"transitions" => array( "nextTurn" => ST_PLAYER_PLAY_DISC, "cantPlay" => ST_NEXT_PLAYER, "endGame" => ST_END_GAME )
),

ST_END_GAME => array(
"name" => "gameEnd",
"description" => clienttranslate("End of game"),
"type" => "manager",
"action" => "stGameEnd",
"args" => "argGameEnd"
)

);
</pre>

We used constants to give an index to the different states. This is to avoid mistakes when we reuse these indexes on the transitions array.

Let's create a file you'll put in <code>modules/php/constants.inc.php</code> :<pre>
<?php

/*
* State constants
*/
const ST_BGA_GAME_SETUP = 1;

const ST_PLAYER_PLAY_DISC = 10;
const ST_NEXT_PLAYER = 11;

const ST_END_GAME = 99;

?>
</pre>

You will also need to add <code>require_once("modules/php/constants.inc.php");</code> at the beginning of the state.inc.php to load these constants.

Now, in <code>reversi.game.php</code> let's create the methods that are declared in this game states description file:
* <code>argPlayerTurn</code>: referenced in the <code>args</code> property of the <code>playerTurn</code> state; this is the name of the method to call to retrieve arguments for this gamestate. Arguments are sent to the client side to be used on <code>onEnteringState</code> or to set arguments in the gamestate description.
* <code>stNextPlayer</code>: referenced in the <code>action</code> property of the <code>nextPlayer</code> state; this is the name of the method to call when this game state become the current game state.

=== Test Your States ===
... and start a new Reversi game.

As you can see on the screen capture below, the BGA framework makes the game jump to our first game state <code>playerTurn</code> right after the initial setup. That's why the status bar contains the description of <code>playerTurn</code> state ("XXXX must play a disc"):

[[File:reversi7.jpg]]

== The rules ==

We will use the <code>getPossibleMoves</code> PHP method to:
* Indicate to the current player where she is allowed to play by returning a list of coordinates
* Check if the player has the right to play in the spot they choose

<blockquote>
Example of getPossibleMoves here https://gist.github.com/leocaseiro/a8bc2851bd0caddd06685b5035937d15
</blockquote>

This is pure PHP programming here, and there are no special things from the BGA framework that can be used. This is why we won't go into details here. The overall idea is:
* Create a <code>getTurnedOverDiscs(x,y)</code> method that returns coordinates of discs that would be turned over if a token would be played at <code>x</code>,<code>y</code>.
* Loop through all free squares of the board and call the <code>getTurnedOverDiscs</code> method on each of them. If at least 1 token is turned over, this is a valid move.

IMPORTANT: Making a database query is slow! Please don't load the entire game board with a SQL query multiple times. In our implementation, we load the entire board once at the beginning of <code>getPossibleMoves</code>, and then pass the board as an argument to all methods.

If you want to look into details, please look at the "utility method" sections of <code>reversi.game.php</code>. If building the tutorial yourself, copy the functions under "Utility functions" comment from the Reversi tutorial.

== Display allowed moves ==

Now we want to highlight the squares where the player can place a disc.

To do this, we add a <code>argPlayerTurn</code> method in <code>reversi.game.php</code>. This method is called on the server each time we enter into <code>playerTurn</code> game state, and its result is transferred automatically to the client-side:

<pre>
function argPlayerTurn(): array
{
return [
'possibleMoves' => $this->getPossibleMoves( intval($this->getActivePlayerId()) )
];
}
</pre>

We use the <code>getPossibleMoves</code> method we just developed.

Each time we enter into a new game state, we use the <code>onEnteringState</code> Javascript method (in the <code>reversi.js</code> file, under "Game & client states"). This lets us use the data returned by the method above on the client side.

<pre>
onEnteringState: function( stateName, args )
{
console.log( 'Entering state: '+stateName );

switch( stateName )
{
case 'playerTurn':
this.updatePossibleMoves( args.args.possibleMoves );
break;
}
},
</pre>

So, when we enter into <code>playerTurn</code> game state, we call our <code>updatePossibleMoves</code> method (under the "Utility methods" section). This method looks like this:

<pre>
updatePossibleMoves: function( possibleMoves )
{
// Remove current possible moves
document.querySelectorAll('.possibleMove').forEach(div => div.classList.remove('possibleMove'));

for( var x in possibleMoves )
{
for( var y in possibleMoves[ x ] )
{
// x,y is a possible move
document.getElementById(`square_${x}_${y}`).classList.add('possibleMove');
}
}

this.addTooltipToClass( 'possibleMove', '', _('Place a disc here') );
},
</pre>
Here's what this does. At first, it removes all <code>possibleMove</code> classes currently applied with the very useful <code>document.querySelectorAll</code> method.

Then it loops through all possible moves our PHP <code>updatePossibleMoves</code> function created for us, and adds the <code>possibleMove</code> class to each corresponding square.

Finally, it uses the BGA framework <code>addTooltipToClass</code> method to associate a tooltip to all those highlighted squares so that players can understand their meaning.

To see the possible moves we need to create a CSS class (<code>possibleMove</code>) that can be applied to a <code>square</code> element to highlight it:
<pre>
.possibleMove {
background-color: white;
opacity: 0.2;
cursor: pointer;
}
</pre>

And here we are:

[[File:reversi8.jpg.jpg]]

== Let's play ==

From now, it's better to restart a game with 2 players, because we are going to implement a complete Reversi turn. The summary of what we are going to do is:
* When we click on a <code>possibleMove</code> square, send the move to the server.
* Server side, check the move is correct, apply Reversi rules and jump to next player.
* Client side, change the token position to reflect the move.

First we associate each click on a square to one of our methods using our Javascript <code>setup</code> method:

<pre>
document.querySelectorAll('.square').forEach(square => square.addEventListener('click', e => this.onPlayDisc(e)));
</pre>

Note the use of the "dojo.query" method to get all HTML elements with "square" class in just one function call. Now, our "onPlayDisc" method is called each time someone clicks on a square.

Here's our "onPlayDisc" method below:

<pre>
onPlayDisc: function( evt )
{
// Stop this event propagation
evt.preventDefault();
evt.stopPropagation();

// Get the cliqued square x and y
// Note: square id format is "square_X_Y"
var coords = evt.currentTarget.id.split('_');
var x = coords[1];
var y = coords[2];

if(!document.getElementById(`square_${x}_${y}`).classList.contains('possibleMove')) {
// This is not a possible move => the click does nothing
return ;
}

this.bgaPerformAction("actPlayDisc", {
x:x,
y:y
});
},
</pre>

What we do here is:
* We stop the propagation of the Javascript <code>onclick</code> event. Otherwise, it can lead to random behavior so it's always a good idea.
* We get the x/y coordinates of the square by using <code>evt.currentTarget.id</code>
* We check that clicked square has the <code>possibleMove</code> class, otherwise we know for sure that we can't play there.
* Finally, we make a call to the server using BGA <code>bgaPerformAction</code> method with argument x and y. This call will check that <code>actPlayDisc</code> action is possible, according to current game state (see <code>possibleactions</code> entry in our <code>playerTurn</code> game state defined above). This check is important to avoid issues if a player double clicks on a square.

Now, we have to manage this <code>actPlayDisc</code> action on the server side. Add a corresponding <code>actPlayDisc</code> method in our game logic (<code>reversi.game.php</code>):

<pre>
function actPlayDisc( int $x, int $y )
{
</pre>
(The function will be called when the front-side action is triggered using the Autowire mechanism, if you want to see how it works in details check https://en.doc.boardgamearena.com/Main_game_logic:_yourgamename.game.php#Actions_%28autowired%29 )
<pre>
$player_id = intval($this->getActivePlayerId());

// Now, check if this is a possible move
$board = $this->getBoard();
$turnedOverDiscs = $this->getTurnedOverDiscs( $x, $y, $player_id, $board );

if( count( $turnedOverDiscs ) > 0 )
{
// This move is possible!
</pre>

...now, we are using the <code>getTurnedOverDiscs</code> method again to check that this move is possible.

<pre>
// Let's place a disc at x,y and return all "$returned" discs to the active player

$sql = "UPDATE board SET board_player='$player_id'
WHERE ( board_x, board_y) IN ( ";

foreach( $turnedOverDiscs as $turnedOver )
{
$sql .= "('".$turnedOver['x']."','".$turnedOver['y']."'),";
}
$sql .= "('$x','$y') ) ";

$this->DbQuery( $sql );
</pre>

... we update the database to change the color of all turned over disc + the disc we just placed.

<pre>
// Update scores according to the number of disc on board
$sql = "UPDATE player
SET player_score = (
SELECT COUNT( board_x ) FROM board WHERE board_player=player_id
)";
$this->DbQuery( $sql );

// Statistics
$this->incStat( count( $turnedOverDiscs ), "turnedOver", $player_id );
if( ($x==1 && $y==1) || ($x==8 && $y==1) || ($x==1 && $y==8) || ($x==8 && $y==8) )
$this->incStat( 1, 'discPlayedOnCorner', $player_id );
else if( $x==1 || $x==8 || $y==1 || $y==8 )
$this->incStat( 1, 'discPlayedOnBorder', $player_id );
else if( $x>=3 && $x<=6 && $y>=3 && $y<=6 )
$this->incStat( 1, 'discPlayedOnCenter', $player_id );
</pre>

... now, we update both player score by counting all disc, and we manage game statistics.

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

$this->notifyAllPlayers( "turnOverDiscs", '', array(
'player_id' => $player_id,
'turnedOver' => $turnedOverDiscs
) );

$newScores = $this->getCollectionFromDb( "SELECT player_id, player_score FROM player", true );
$this->notifyAllPlayers( "newScores", "", array(
"scores" => $newScores
) );
</pre>

... then we notify about all these changes. We are using for that 3 notifications (<code>playDisc</code>, <code>turnOverDiscs</code> and <code>newScores</code> that we are going to implement on client side later). Note that the description of the <code>playDisc</code> notification will be logged in the game log.

<pre>
// Then, go to the next state
$this->gamestate->nextState( 'playDisc' );
}
else
throw new BgaSystemException( "Impossible move" );
}
</pre>

... finally, we jump to the next game state if everything goes fine (<code>playDisc</code> is the name of a transition in the <code>playerTurn</code> game state description above which leads to state 11 which is <code>nextPlayer</code>).

To make the statistics work, we have to initialize them in <code>stats.json</code>:

<pre>
{
"player": {
"discPlayedOnCorner": {
"id": 10,
"name": "Discs played on a corner",
"type": "int"
},
"discPlayedOnBorder": {
"id": 11,
"name": "Discs played on a border",
"type": "int"
},
"discPlayedOnCenter": {
"id": 12,
"name": "Discs played on board center part",
"type": "int"
},
"turnedOver": {
"id": 13,
"name": "Number of discs turned over",
"type": "int"
}
}
}
</pre>

A last thing to do on the server side is to activate the next player when we enter the <code>nextPlayer</code> game state (in the <code>reversi.game.php</code> file, under "Game state reactions"):

<pre>
function stNextPlayer(): void
{
// Active next player
$player_id = intval($this->activeNextPlayer());

// Check if both player has at least 1 discs, and if there are free squares to play
$player_to_discs = $this->getCollectionFromDb( "SELECT board_player, COUNT( board_x )
FROM board
GROUP BY board_player", true );

if( ! isset( $player_to_discs[ null ] ) )
{
// Index 0 has not been set => there's no more free place on the board !
// => end of the game
$this->gamestate->nextState( 'endGame' );
return ;
}
else if( ! isset( $player_to_discs[ $player_id ] ) )
{
// Active player has no more disc on the board => he looses immediately
$this->gamestate->nextState( 'endGame' );
return ;
}

// Can this player play?

$possibleMoves = $this->getPossibleMoves( $player_id );
if( count( $possibleMoves ) == 0 )
{

// This player can't play
// Can his opponent play ?
$opponent_id = (int)$this->getUniqueValueFromDb( "SELECT player_id FROM player WHERE player_id!='$player_id' " );
if( count( $this->getPossibleMoves( $opponent_id ) ) == 0 )
{
// Nobody can move => end of the game
$this->gamestate->nextState( 'endGame' );
}
else
{
// => pass his turn
$this->gamestate->nextState( 'cantPlay' );
}
}
else
{
// This player can play. Give him some extra time
$this->giveExtraTime( $player_id );
$this->gamestate->nextState( 'nextTurn' );
}
}
</pre>

Now, when we play a token, the rules are checked and the token appears in the database.

[[File:reversi9.jpg]]

Of course, as we don't manage notifications on client side, we need to press F5 after each move to see the changes on the board.

== Make the move appear automatically ==

Now, what we have to do is process the notifications sent by the server and make the move appear on the interface.

In our <code>setupNotifications</code> method in <code>reversi.js</code>, we register 2 methods for the 2 notifications we created at the previous step (<code>playDisc</code> and <code>turnOverDiscs</code>):

<pre>
const notifs = [
['playDisc', 500],
['turnOverDiscs', 1500],
['newScores', 1],
];

notifs.forEach((notif) => {
dojo.subscribe(notif[0], this, `notif_${notif[0]}`);
this.notifqueue.setSynchronous(notif[0], notif[1]);
});
</pre>

We will associate each of our 3 notifications with a method prefixed with <code>notif_</code>. We also define these notifications as "synchronous", with a duration in millisecond. It tells the user interface to wait some time after executing the notification, to let the animation end before starting the next notification. In our specific case, the animation will be the following:
* Make a disc slide from the player panel to its place on the board
* (wait 500ms)
* Make all turned over discs blink (and of course turned them over)
* (wait 1500ms)
* Update the player scores
* (no real delay on this one)

The second part of the code is a generic thing to automatically bind the notifs we configured to the <code>notif_<notifName></code> functions we are about to create.

Let's have a look now on the <code>playDisc</code> notification handler method:

<pre>
notif_playDisc: function( notif )
{
// Remove current possible moves (makes the board more clear)
document.querySelectorAll('.possibleMove').forEach(div => div.classList.remove('possibleMove'));

this.addDiscOnBoard( notif.args.x, notif.args.y, notif.args.player_id );
},
</pre>

No surprise here, we re-used some existing stuff to:
* Remove the highlighted squares.
* Add a new disc on board, coming from player panel.

Now, here's the method that handles the <code>turnOverDiscs</code> notification:

<pre>
notif_turnOverDiscs: function( notif )
{
// Get the color of the player who is returning the discs
var targetColor = this.gamedatas.players[ notif.args.player_id ].color;

// Made these discs blinking and set them to the specified color
for( var i in notif.args.turnedOver )
{
var disc = notif.args.turnedOver[ i ];

// Make the disc blink 2 times
var anim = dojo.fx.chain( [
dojo.fadeOut( { node: 'disc_'+disc.x+''+disc.y } ),
dojo.fadeIn( { node: 'disc_'+disc.x+''+disc.y } ),
dojo.fadeOut( {
node: 'disc_'+disc.x+''+disc.y,
onEnd: node => $(node).dataset.color = targetColor,
} ),
dojo.fadeIn( { node: 'disc_'+disc.x+''+disc.y } )

] ); // end of dojo.fx.chain

// ... and launch the animation
anim.play();
}
},
</pre>

The list of the discs to be turned over has been made available by our server side code in <code>notif.args.turnedOver</code> (see previous paragraph). We loop through all these discs, and create a complex animation using <code>dojo.Animation</code> for each of them. The complete documentation on dojo animations [http://dojotoolkit.org/documentation/tutorials/1.6/animation/ can be found here].

In few words: we create a chain of 4 animations to make the disc fade out, fade in, fade out again, and fade in again. At the end of the second fade out, we change the color of the disc. Finally, we launch the animation with <code>play()</code>.

And Also the notification to update the scores:

<pre>
notif_newScores: function( notif )
{
for( var player_id in notif.args.scores )
{
var newScore = notif.args.scores[ player_id ];
this.scoreCtrl[ player_id ].toValue( newScore );
}
},
</pre>

[[Category:Studio]]

Create a game in BGA Studio: Complete Walkthrough

2024-09-27T15:40:05Z

Sguzzer Gunayer: /* Create Database Schema */

== Introduction ==

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

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

If you're stuck or have questions about this page post on [https://forum.boardgamearena.com/viewforum.php?f=12 BGA Developers forum].
If you're uncomfortable posting on the public forum you can send messages directly to developers who post answers on that forum but NOT the BGA admins.
If you find typos in this wiki, fix them.

== Select a First Game ==

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

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

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

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

If your goal was to fix bugs in an existing project, first try to locate it on Studio, but note that projects developed by BGA admins are not in Studio. Then get read-only access to the project, and create your own as a copy of the existing one. Contact a project admin about getting write access to the original project, or ask if they are willing to apply your patches.

If you want to take over an existing project, first ask on the forum to see if the project is abandoned, then get read-only access (via project list) and see if it's worth using the existing project. If it has no code or graphics, then just start from the scratch. Don't worry about the project name; it can be renamed later.

== Create a project ==

If you have not already, you have to create a project in BGA Studio for this game. If the original game name is taken use gamenameYOURINITIALS
template, i.e."heartsla". Don't worry too much about the name, if the game is good enough to publish, it will be renamed to its original name.

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

Second, modify the text in .tpl file, reload the page in the browser and make sure your ftp sync works as expected.
Note: if you have not setup [http://en.doc.boardgamearena.com/Tools_and_tips_of_BGA_Studio#File_Sync FTP auto-sync] yet, do it now, manually copying files is a no-starter.

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

== Development Tools ==

At some point, you need to setup your development environment which consists of multiple tools, such as
* Editor or IDE
* Browser with dev tools
* File sync tools
* BGA Web tools
* Image manipulation tools
* Version control tools

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

== Hook version control system ==

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

== Obtain game graphics ==

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

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

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

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

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

[[File:Rrr_search.png]]

== Obtain game documentation ==

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

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

== Update game info and box graphics ==

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

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

The next step is to replace game_box.png with proper images, usually, you can find all images including the publisher logo on the boardgamegeek website.

Game metadata images, such box image are now managed in separate tool.

Details about images can be found here: [[Game art: img directory]].

[[File:Gamepanel_sharedcode.png]]

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

== Fix source copyright ==

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

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

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

== Reduce the Rules ==

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

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

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

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

So every game element would be in the

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

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

== Create Initial Layout and Game Graphics ==

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

There are a few ways how the html could have been generated. You could have started with nothing and generate
it all by javascript, or you could have started with complete game markup in html and make javascript just hide and move pieces around. BGA framework also provides a third way, which is mix of both, plus a template engine to generate HTML using PHP. The only thing that is really annoying about the template engine is that you cannot put any translatable strings in the template (which means any visible text at all). If you are using the template approach all strings have to be extracted as variables and injected through PHP (.view.php). This page explains the template engine in great detail:[[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl|Template Engine]].

The other disadvantage of the template engine is you cannot run and debug it locally, in the beginning of development it's a lot faster run off local pages,
you can do it with some trickery described here [[Tools_and_tips_of_BGA_Studio#Speed_up_CSS_development_and_layout|Tools and Tips for BGA Studio]]

During this step you have to decide what technical solutions you will be using, such as
* Use inline positioning of all moving pieces, controlled by JS. There are a few classes that already exist in Studio to help with that (see [[Studio#Game_interface_.28Client_side.29|Game Interface - Client Side]]). OR use html/css layout engine to position pieces (my personal choice).
* Use BGA template engine OR create all ui elements by JS OR manually write or generate complete html markup. The game usually contains 200-300 pieces, it seems wrong but actually its faster to type all of this up in html/css when trying write than debug code for page generator.
Static HTML markup also means you have to use players color or abstracted player number (such as red is 1, blue is 2) not player id's anywhere in JS, since player id is dynamic by nature.

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

Here are some specific examples:

'''Game Board'''

Create entry in .tpl file for the board, it will be static entry as we never need to create this dynamically
<pre>
<div id="board" class="board shadow board4p"> ... </div>
</pre>
Create entry in .css file for this board and other board variants (in example below we have 4 ppl board which is diffrent than 2 ppl board)
<pre>
.board {
position: relative;
width: 980px;
height: 433px;
margin-bottom: 5px;
}

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

'''Game Board Slots'''

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

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

Entry in template inside the "board" div
<pre>
<div id="slot_action_2" class="slot_action_2 slot_action slot_w_1 slot"></div>
</pre>

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

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

In CSS these guys will use "sprite" images with transparency, so it will look like this this:
<pre>
.meeple {
background-image: url(img/tokens.png);
width: 25px;
height: 25px;
}
.meeple_ff0000 { /* red */
background-position: 14% 0%;
}
</pre>
As for creation you can either generate them using template (where whole thing wrapped in template block and {COLOR} replace with all possible colors in .view.php
<pre>
<div id="meeple_{COLOR}_1" class="meeple meeple_{COLOR} meepleable"></div>
<div id="meeple_{COLOR}_2" class="meeple meeple_{COLOR} meepleable"></div>
...
</pre>

Or you can declare a template js var in .tpl file
<pre>
var jstpl_mepple = '<div id="meeple_${color}_${num}" class="meeple meeple_${color} meepleable"></div>'; // this is in .tpl file at the bottom
</pre>
and create in js, like this
<pre>
var tokenDiv = this.format_block('jstpl_mepple', {
"color" : color,
"num" : i
}); // this in js code somewhere before placing it
</pre>
If you dealing with cards and decks, there are pre-build components that can generate stuff for you.

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

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

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

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

[[File:Injected_text.png]]

== Create Database Schema ==

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

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

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

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

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

Example: '''The card game'''

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

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

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

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

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

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

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

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

'''Chess:'''

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

'''Classic card game'''

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

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

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

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

== Implement Game Setup ==

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

It very hard to debug this method, so this is how we recommend to structure it:

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

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

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

function initTables() {
try {
$players = $this->loadPlayersBasicInfos();
// code the function
$this->activeNextPlayer(); // just in case so its not 0
$this->initStats(); // to be coded
// Setup the initial game situation here
$this->initGameTables(); // to be coded
// beggining of the turn for active player (if player state if first state)
$player_id = $this->getActivePlayerId();
$this->incStat(1, 'turns_number', $player_id);
$this->incStat(1, 'turns_number');
} catch ( Exception $e ) {
// logging does not actually work in game init :(
// but if you calling from php chat it will work
$this->error("Fatal error while creating game");
$this->dump('err', $e);
}
}
</pre>

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

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

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

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

$values=[];
$values [] = "('meeple_ff0000_1', 'home_ff0000', 0)"; // this is actually string not array
...
$sql = "INSERT INTO tokens (token_id, place_id, state) VALUES " . implode($values, ',');
$this->DbQuery($sql);

== Implement one time game model synchronization ==

Now at any point in the game we need to make sure that database information can be reflected back in UI, so we fix <code>getAllDatas</code> function to return all possible data we need to reconstruct the game. The template for <code>getAllDatas</code> is already taking care of player info, but you have to alter it to return all other data from database visible to the "current" player.

After that on the client side we should display this data, so in your .js file in <code>setup</code> function (which is the receiver of <code>getAllDatas</code>) you add calls that handle data send by server, usually by calling animation function such as "<code>placeToken</code>" or "<code>placeCard</code>".

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

* Extra player info.
* Material file variables as unfortunately they are not included automatically. Note - I strongly recommend using only one variable for generic data information, such as <code>$this->token_types</code>. If you start splitting it i.e. <code>card_types</code>, <code>meeple_types</code>, <code>building_types</code> - it will be very hard to deal with this programmatically as it will be lots of switches. Also call it the same as in php - otherwise its really hard to correlate.
* Game options (if you know how to access them on client without passing via <code>getAllData()</code> edit this wiki). Example has generic code to pass all options, but you can use custom individual options.
* Dump of database tables filtered by current player view.
* To be fancy you can also include php constants so you can access them in js as well, example not included.

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

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

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

return $result;
}
</pre>

== Create State Machine ==

Now you need to create a game state machine.

The state handling is spread across 4 files, so you have to make sure all the pieces are connected together. The state machine <code>states.inc.php</code> defines all the states, and function handlers on php side in a form of string, and if any of these functions are not implemented it would be very hard to debug because it will break in random places.

Please first watch this again [http://www.slideshare.net/boardgamearena/bga-studio-focus-on-bga-game-state-machine BGA game state machine] and then please read [[Your game state machine: states.inc.php]].

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

It is important to implement proper state handling on the client, usually it results in big <code>switch</code> in <code>onUpdateActionButtons</code> method.
<pre>
onUpdateActionButtons: function(stateName, args) {
console.log('onUpdateActionButtons: ' + stateName + " " + this.isCurrentPlayerActive() + " args:", args);
if (!this.isCurrentPlayerActive()) return;
switch (stateName) {
case 'playerTurn':
dojo.query('.card').addClass('active_slot'); // activate board elements, when using static connector, see user input below
// add buttons
this.addActionButton('button_pass', _('Pass'), () => { this.bgaPerformAction('pass'); });
// case...
}
if (this.on_client_state && !$('button_cancel')) {
this.addActionButton('button_cancel', _('Cancel'), 'cancelLocalStateEffects', 0, 0, 'gray');
this.addTooltip('button_cancel', _("This means cancel current action and start thinking"), '');
}
},

</pre>

I keep <code>onLeavingState</code> pretty generic (and <code>onEnteringState</code> just for logging)
<pre>
onLeavingState: function (stateName) {
console.log('Leaving state: ' + stateName);
dojo.query('.active_slot').removeClass('active_slot');
dojo.query('.selected').removeClass('selected');
},

</pre>
== Handle Turn Order ==

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

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

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

== Hook User Input ==

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

Usually all pieces will be hooked to <code>onclick</code> during JS "<code>setup</code>" method, in addition if you create elements during server notification they have to be hooked up at that time.

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

So classic is static handlers, means handler is added in setup method using framework connect function:

this.connect( $('my_element'), 'onclick', 'onClickOnMyElement' );

This is what is advertised in tutorials, however this is best suited for static html model - where elements are not deleted and recreated. When elements created dynamically if you using this method please be aware of memory leaks - this method stores the pointer to DOM element in arrays of handlers (to be able to disconnect later), but if element is deleted you must call <code>this.disconnect</code> before deleting with same node reference, or it will leak.

If you using this method your handlers usually look like big ugly switch because it usually depending on state it will do right thing or deny action, typically it will look this this:
onCard: function(event) {
dojo.stopEvent(event);
var id = event.currentTarget.id;
console.trace("on slot " + id);
if (!id) return null;
// check player is active
if (!this.isCurrentPlayerActive()) {
this.showMessage(__("lang_mainsite", "This is not your turn"), "error");
return false;
}
// check node is marked with "active_slot" class (class name is whatever you want)
if (!dojo.hasClass(id, 'active_slot')) {
this.showMoveUnauthorized();
return false;
}
switch (this.gamedatas.gamestate.name) {
case 'playerTurn': // in this case we directly sending data to the server
this.bgaPerformAction('playCard', { id }); // note that this wrapper also calls 'checkAction' on action parameter
return true;
case 'playerDiscard': // in this case we need to collect more information, so we using cient state for that
dojo.addClass(id,'selected'); // mark card
this.setClientState("client_playerTurnSelectBonus", {
descriptionmyturn: _('${you} must select bonus for discard'),
});
return true;
default:
this.showMoveUnauthorized();
return false;
}
},

You can also manage listeners yourself (vanilla event listeners or dojo). In this case be aware of registering double listener. See more example in [[Game_interface_logic:_yourgamename.js#Players_input|Player's Input]].

Alternative to static handler are dynamic handlers which are only installed on elements that are active for specific game state, given the example above we would register the listeners in <code>playerTurn</code> state, i.e. in <code>onUpdateActionButtons</code> for <code>playerTurn</code>:
<pre>
dojo.query('.card').forEach((node) => {
dojo.addClass(node, 'active_slot');
dojo.addClass(node, 'temp_click_handler');
this.connect(node, 'click', event => this.bgaPerformAction('playCard', { id: event.currentTarget.id }));
});
</pre>
Above we did not need to do the heavy validation because we only presumably added handler in right state to right node and right active player (and removed correctly in between!)

And in <code>onLeavingState</code> we will disconnect all of them (important!):
<pre>
dojo.query('.temp_click_handler').forEach((node) => {
dojo.removeClass(node, 'active_slot');
dojo.removeClass(node, 'temp_click_handler');
this.disconnect(node, 'click');
});
</pre>

When user clicks on something, client sends an ajax call to server, server processes it and updates database, server sends notification in response, client hooks animations to server notification. See [[Game_interface_logic:_yourgamename.js#Notifications|JS Notifications]].

Exception to this is client states, if you need to process two step user interaction such as select meeple, place meeple, you may want to avoid sending data to server until step is complete (which may involve direct client side animation). See [[BGA_Studio_Cookbook#Multi_Step_Interactions:_Select_Worker.2FPlace_Worker_-_Using_Selection|Multi-Step Interactions]]

Part of the sending notifications would be to update player's scoring, BGA uses standard control for score (on JS side), see [[Game_interface_logic:_yourgamename.js#Update_players_score|Update Player's Score]].

In BGA there is only two ways interact with the server (officially)
* Initial data dump - when JS client starts it gets all current data via setup() method
* Game actions - <code>bgaPerformAction</code>/ajaxcall from client, it returns error or ok (not data), then server send butch of notifications to client

Note current ajaxcall is super vebosy, <code>bgaPerformAction</code> should be used instead.

When you insert a single action you have to update multiples files:
* in ggg.js add ajaxcall, i.e. something like
this.addActionButton('pass', _('Pass'), () => this.bgaPerformAction('pass'));
* in states.php - add action 'pass' to list of possible actions
'possibleactions' => ['pass','playCard']
* in <code>action.php</code> - add action handler, see https://en.doc.boardgamearena.com/Players_actions:_yourgamename.action.php
* in <code>game.php</code> - add action handler, there you must do the following:
** call <code>checkAction</code> to validate the action.
** possible do more game specific check to validate what player doing is legal (even its not possible from your js side - player can cheat - not allow that).
** do some database manipulations, using access API.
** send notifications - this is the "reply" for action.
** transition to new state (it very rare that user will remain in the same state, except for multi-active states).
* back to ggg.js add notification subscription and notification handler (two separate things).

== Implement Notification handling and Animation ==

To handle notification you have to subscribe to it and implement the handlers, see [[Game_interface_logic:_yourgamename.js#Notifications|JS Notifications]].

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

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

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

* Implement game progression (<code>getGameProgression()</code> in php).
* Implement Zombie turn (<code>zombieTurn()</code> in php).
* Define and implemented some meaningful statistics for your game (i.e. total points, point from source A, B, C...).
* The games logs should explain what happened if player was not looking.
* You need to implemented tiebreaking (using aux score field) and updated tiebreaker description in meta-data.
* Make sure all UI strings are marked for translation.
* UI elements which are images (i.e. tokens, cards) should have tooltips.

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

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

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

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

== Level Up ==

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

* Add game extentions and variants using gameoptions file.
* Add user preferences for customizations.
* Use theming! That involves replacing hardwood background, changing tooltips, using different sounds, different fonts, changing state prompt and logs.
* You can use fancy scoring board at the end of game instead of default nothing.
* And finally super cool dice rolling, card flipping and victory points evaporating effects.

[[Category:Studio]]

Tutorial hearts

2024-09-26T21:36:53Z

Sguzzer Gunayer: /* Game Database and Game Initialisation */

{{Studio_Framework_Navigation}}

== Introduction ==

Using this tutorial, you can build a complete working game on the BGA environment: Hearts.

Before you read this tutorial, you must:
* Read the overall presentations of the BGA Framework ([[Studio|see here]]).
* Know the rules for Hearts
* Some-what know the languages used on BGA: PHP, SQL, HTML, CSS, Javascript
* Set up your development environment [http://en.doc.boardgamearena.com/First_steps_with_BGA_Studio First Steps with BGA Studio]
* As part of setup you have to have access to your ftp home folder in studio, which would have the full 'hearts' game source code. We will be using some resources of this game in this tutorial, so copy it over to local disk if you have not done so.

If you are stuck or have question about this tutorial, post on [https://forum.boardgamearena.com/viewforum.php?f=12 BGA Developers forum]

== Create your first game ==

If you have not already, you have to create a project in BGA Studio. For this tutorial you can create a project heartsYOURNAME where
YOURNAME is your developer login name. You can also re-use the project you have created for the "First Steps" tutorial above.
With the initial skeleton of code provided, you can already start a game from the BGA Studio.

1. Find and express start the game in turn-based mode with 4 players. Make sure it works. If you want to see the game as 2nd player press red arrow button on the player panel to switch to that player. More details can be found in [[First_steps_with_BGA_Studio]]

2. Modify the text in heartsYOURNAME_heartsYOURNAME.tpl, reload the page in the browser and make sure your ftp sync works as expected.
Note: if you have not setup auto-sync do it now, manually copying files is a no-starter.

3. Express stop from settings menu (the gear icon).

<i>Note: please do '''not''' use the hearts project code as a base. This tutorial assumes you started with a TEMPLATE project with no prior modifications. Using the hearts project as a base will be very confusing and you won't be able to follow all the steps.
</i>

<b>Attention!!!</b> Very important note about reloading, if you don't remember this you may spend hours debugging. The browser caches images. If you change any of these files, you have to do "full reload" which is usually Ctrl+F5 (or Ctrl+reload button on browser) not just a regular reload.

== Hook version control system ==

For a real game, or even for this tutorial, we recommend committing the code to version control right from the start. You are going to find yourself in a situation where the game doesn't even start anymore and no way of debugging it, unless you have a way to revert. That is where version control becomes very handy. If you are not familiar with version control (e.g. [https://git-scm.com/docs/gittutorial git]) then at least back up your files after each major change. Start now.

Code for this tutorial available is on github: https://github.com/elaskavaia/bga-heartsla

Different revisions represent different steps along the process, starting from original template to a PARTIAL game. The full game can be found in your FTP home folder.

== Update game infos and box graphics ==

Even it does nothing yet, always start by making sure the game looks decent in the game selector, meaning it has nice box graphics and its information is correct. For that we need to edit [[Game_meta-information: gameinfos.inc.php|gameinfos.inc.php]].

For a real game, you would go to [http://boardgamegeek.com BoardGameGeek], find the game, and use the information from BGG to fill in the gameinfos.

So let's do that. Find "hearts" on BoardGameGeek. (Hint: Original release 1850 :))

You can fill in the year of publishing and bgg id, put ''Public Domain'' under publisher (for a real game, leave an empty string so it won't be displayed), and a publisher id of 171 for public domain. And as designer and author you can just put your own name just for fun. Set number of players to 4.

// Players configuration that can be played (ex: 2 to 4 players)
'players' => array( 4 ),

'''Important step''': you have to refresh the information in the Studio website through the control panel. So go to Control Panel -> Manage Games -> heartsYOURNAME
and press Reload for 'Reload game informations'.

The next step would be to replace '''game_box.png''' with nicer images. This can be done from the [[Game metadata manager]].

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

<i>Note: if you had run the game before with less than 4 players there is a bug that will prevent you from running it with 4 only (if you did not run it before or run it with 4 players as instructed stop reading this note), to workaround revert back to original players array (i.e. 1,2,3,4), reload game options, then create a table with 4 players, exit that game table, then change gameoptions to 4 only as above, reload game options, create table again.</i>

Code Rev [https://github.com/elaskavaia/bga-heartsla/tree/4b3a73eeb5acae961ade18473af119e8ce8d1a8f]

== Layout and Graphics ==

In this section we will do graphics of the game, and main layout of the game.

First copy a sprite with cards image from [https://github.com/elaskavaia/bga-heartsla/blob/4b3a73eeb5acae961ade18473af119e8ce8d1a8f/img/cards.jpg hearts img/cards.jpg] into img/ folder of your project. Project hearts is mounted to your home directory on bga server.
<blockquote>There are better quality deck of cards image at https://en.doc.boardgamearena.com/Common_board_game_elements_image_resources</blockquote>

Details about images can be found here: [[Game art: img directory]].

Edit .tpl to add some divs to represent player table and hand area

<pre>
<div id="myhand_wrap" class="whiteblock">
<h3>My Hand</h3>
<div id="myhand">
</div>
</div>
</pre>

If you refresh you should see now white area with My Hand title.

[[File:Heartsla-tpl2.png]]

Now lets add a card into the hand, just so you can feel it. Edit .tpl and a playertablecard div inside a hand div
<pre>
...
<div id="myhand">
<div class="playertablecard"></div>
</div>
...
</pre>

Edit .css file
<pre>
.playertablecard {
display: inline-block;
position: relative;
margin-top: 5px;
width: 72px;
height: 96px;
background-image: url('img/cards.jpg'); /* temp hack to see it */
}
</pre>

When you change existing graphics files remember that you have to FORCE-reload page, i.e. Ctrl-F5, otherwise its cached.

You should see this:

[[File:Heartsla-tpl3.png]]

Awesome! Now lets do the rest of layout.

There are few ways of how html could have been generated, you could have start with nothing and generate
all by java script. Or you could have started with complete game markup in html and make java script just hide and move pieces around. BGA framework provides also a third way which is mix of both plus template engine to generate HTML using php. So lets do that.

Note: generating blocks in js only is probably simpler now with template strings.

Change .tpl file to have this inside
<pre>
<div id="playertables">


<div class="playertable whiteblock playertable_{DIR}">
<div class="playertablename" style="color:#{PLAYER_COLOR}">
{PLAYER_NAME}
</div>
<div class="playertablecard" id="playertablecard_{PLAYER_ID}">
</div>
</div>


</div>

<div id="myhand_wrap" class="whiteblock">
<h3>{MY_HAND}</h3>
<div id="myhand">
<div class="playertablecard"></div>
</div>
</div>
</pre>

What we did is we added "block" playerhandblock, it is marked up using html comments. {VAR} notation is used
to inject variables and
<pre>

inside

</pre>
effectively allows us to do template loops.

In .view.php, fill in the implementation of <code>build_page</code> like so:
<pre>
public function build_page($viewArgs)
{
// Get players
$players = $this->game->loadPlayersBasicInfos();

$template = $this->getGameName() . "_" . $this->getGameName();

$directions = array( 'S', 'W', 'N', 'E' );

// this will inflate our player block with actual players data
$this->page->begin_block($template, "playerhandblock");
foreach ( $players as $player_id => $info ) {
$dir = array_shift($directions);
$this->page->insert_block("playerhandblock", array ("PLAYER_ID" => $player_id,
"PLAYER_NAME" => $players [$player_id] ['player_name'],
"PLAYER_COLOR" => $players [$player_id] ['player_color'],
"DIR" => $dir ));
}
// this will make our My Hand text translatable
$this->tpl['MY_HAND'] = $this->_("My hand");
}
</pre>

What it does is for each player we have it will replicate the html between  and  tags, substituting the variable denoted by {XXX}
with the values you provide. The DIR variable in this case we pulling from directions array (where array_shift will take first element and remove it from the array).

Reload. If everything went well you should see this:

[[File:Hearts all rows.png|alt=Display a list of all players, with a dummy card in each position]]

These are "tableau" areas for 4 players plus My hand visible only to one player. They are not exactly how we wanted them to be because we did not edit .css yet.

Now edit .css, add these lines after import before our previous definition

<pre>
/** Table layout **/

#playertables {
position: relative;
width: 710px;
height: 340px;
}

.playertablename {
font-weight: bold;
}

.playertable {
position: absolute;
text-align: center;
width: 180px;
height: 130px;
}

.playertable_N {
left: 50%;
top: 0px;
margin-left: -90px; /* half of 180 */
}
.playertable_S {
left: 50%;
bottom: 0px;
margin-left: -90px; /* half of 180 */
}
.playertable_W {
left: 0px;
top: 50%;
margin-top: -55px; /* half of 130 */
}
.playertable_E {
right: 0px;
top: 50%;
margin-top: -55px; /* half of 130 */
}
</pre>

Now you force Reload and you should see this:
[[File:Heartsla-tpl5.png]]

This is almost all we need for graphics and layout, there are few tweaks left there but lets do some more heavy lifting now.

<i>Note: if you did not see changes you may have not force reloaded, force means you use Ctrl+F5 or Cltr+Shift-R, if you don't "force" browser will use cached version of images! Which is not what you just changed</i>

<i>Another Note: In general if you have auto-sync you don't need to reload if you change game.php file, you need normal reload if you change js, and force reload for images. If you changed state machine or database you likely need to restart the game.</i>

== Game Interface JS Stock ==

The BGA framework provides a few out of the box classes to deal with cards. The client side
contains a class called [[Stock]] and it can be used for any dynamic html "pieces" management that uses
common sprite images. On the server side we will use the [[Deck]] class which we discuss later.

If you open cards.jpg in an image viewer you will see that it is a "sprite" image - a 13x4 grid of images stitched together,
which is a very efficient way to transport images. So we will use the Stock class to mark up these images and create
"card" divs for us.

First, we need to add '''ebg/stock''' as a dependency in the hearts.js file:
<pre>
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/stock" /// <==== HERE
],
</pre>

Then add this to the Javascript constructor, this will define size of our cards
<pre>
console.log('hearts constructor');
this.cardwidth = 72;
this.cardheight = 96;
</pre>

The stock is initialized in the Javascript "setup" method like this:
<pre>
// TODO: Set up your game interface here, according to "gamedatas"

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

As parameters of the "create" method, we provided the width/height of an item (a card), and the container div "myhand" - which is an id of "div" element from our .tpl file representing a player hand.

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

Here's how we tell stock what item types to display:
<pre>
this.playerHand.image_items_per_row = 13; // 13 images per row

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

And add this function to the utilities section
<pre>
// Get card unique identifier based on its color and value
getCardUniqueId : function(color, value) {
return (color - 1) * 13 + (value - 2);
},
</pre>

Explanations:
* At first, we tell the stock component that our CSS sprite contains 13 items per row. This way, it can find the correct image for each card type id.
* Then for the 4x13 cards, we call the '''addItemType''' method that creates the type. The arguments are the type id, the weight of the card (for sorting purpose), the URL of our CSS sprite, and the position of our card image in the CSS sprite. It happens to be the same number in our case.

Note: we need to generate a unique ID for each type of card based on its color and value. For that we create a function '''getCardUniqueId'''. The type is the unique identifier of the TYPE of the card, e.g., the queen of spades encoded as an integer. If our deck had 2 standard card decks we would have had 2 queens of spades; they would share the same type and the same image but would have different ids. NOTE: It's unfortunate that they named this '''getCardUniqueId'''; it should have been '''getCardUniqueType''', because it really isn't an id, but a TYPE of card. The type of the item should either be a reversible function of its properties (i.e., kind of suite * 13 + value) or just an enumerator described in material.inc.php. In this specific case it's a synthetic type id, which also the same as the number of the card in the sprite image (i.e., if you enumerate each image in sprite going left to right, then top to bottom).

Now let's add the 5 of Hearts to the player's hand just for fun (this code will go in setup method after types initialization):

<pre>
// 2 = hearts, 5 is 5, and 42 is the card id, which normally would come from db
this.playerHand.addToStockWithId( this.getCardUniqueId( 2, 5 ), 42 );
</pre>

This will add the card with id 42 and type 16 ( (2-1)*13+(5-2)=16 ).

Note that number 16 would not be something you can see in database, Deck database will have separate field for type and type_arg where type is suite and type_arg is number, so its not the same thing, but you can use same formula to convert. Number 42 on the other hand would be id field in database. But we get to database in the later section.

If you reload now you should see the 5 of hearts in "your hand".

Stock control can handle clicking on items and forms the selection. You can immediately react to selection
or you can query it later; for example when user presses some other button.

Let's hook it up. Add this in the setup method in .js file, after this.playerHand is initialised:

dojo.connect( this.playerHand, 'onChangeSelection', this, 'onPlayerHandSelectionChanged' );

Then find the Player's action comment section in .js file and add a handler after the comment:

<pre>
onPlayerHandSelectionChanged: function() {
var items = this.playerHand.getSelectedItems();

if (items.length > 0) {
if (this.checkAction('actPlayCard', true)) {
// Can play a card

var card_id = items[0].id;
console.log("on playCard "+card_id);

this.playerHand.unselectAll();
} else if (this.checkAction('actGiveCards')) {
// Can give cards => let the player select some cards
} else {
this.playerHand.unselectAll();
}
}
},
</pre>

''Note : If you already have an example handler <code>onCardClick: function( card_id )</code>, go ahead and remove that handler, it is a duplicate of what we are implementing in this tutorial and may cause issues later on.''

The function name of the handler is 4th parameter of the dojo.connect function. Make sure you spell it correctly or there will be unpredictable effects.

Now if you reload, open the Javascript Console (F12), and then click on the card in My Hand, you should see:
on playCard 42
printed on the console

''Note : You need to be the active player to have rights to play a card and so log your message in the console''

== Game Database and Game Initialization ==

Next step, you want to design a game database and setup a new game (on the server side).
For that we need to a) modify the database schema to add our cards data b) add some global variables into
the existing globals table.

To modify the schema, first exit your existing game(s). Open '''dbmodel.sql''' file and uncomment the card table creation.

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

This is the "card" table which will be managed by the Deck php class.

In addition we want a little piece of information in the players table:

-- add info about first player
ALTER TABLE `player` ADD `player_first` BOOLEAN NOT NULL DEFAULT '0';

Not sure why they put this into the player table, as we could use a global db variable to hold first player as easily.
But I am just following the existing code more-or-less.

Next we finally get into .game.php class, where the main logic and db interaction would be. Find php constructor which should be
function __construct( )
This is first function in a file. Add this code to constructor.
<pre>
parent::__construct();
$this->initGameStateLabels( array(
"currentHandType" => 10,
"trickColor" => 11,
"alreadyPlayedHearts" => 12,
) );

$this->cards = $this->getNew( "module.common.deck" );
$this->cards->init( "card" );
</pre>

Here we are initializing three "Game State Variables" which are variables stored in the database. They are integers.
It must start with values higher or equal to 10 since values lower than 10 are reserved. These values are stored by numeric ids
in the database, but in the php we associate them with string labels for convenience of access.

The variables are:

* "trickColor": numbers from 1 to 4 that map to card suit (not sure why it's called color; maybe it's a translation from French);
* "alreadyPlayedHearts": a boolean flag (0 or 1) indicating whether somebody used hearts on the trick;
* "currentHandType": stores the value to indicate who to give cards to during exchange.

The next 2 lines are creating $this->cards object and associating it with "card" table in the the database.

<i>If we called db table 'foo' instead of 'card' the last statement would have been $this->cards->init( "foo" )</i>

At this point I would start a new game and make sure it starts, then exit.

<i>
If you made a mistake
in the .sql or php constructor the game won't start, and good luck debugging it. (That is why it's important to check
once in a while to make sure it still starts while you remember what you have changed.)
</i>

Code Rev [https://github.com/elaskavaia/bga-heartsla/tree/e3a049257b592ff6167688d4d344f8a83d349b08]

Now we can go to game initialization '''setupNewGame''' in game.php. This method is called only once when the game is created.

In your template project you should have code that deals with player table, just leave it as is. Start inserting the
other code after "Start the game initialization" comment.
<pre>
// Init global values with their initial values

// Note: hand types: 0 = give 3 cards to player on the left
// 1 = give 3 cards to player on the right
// 2 = give 3 cards to player opposite
// 3 = keep cards
$this->setGameStateInitialValue( 'currentHandType', 0 );

// Set current trick color to zero (= no trick color)
$this->setGameStateInitialValue( 'trickColor', 0 );

// Mark if we already played hearts during this hand
$this->setGameStateInitialValue( 'alreadyPlayedHearts', 0 );
</pre>

Here we initialize all the globals to 0.

Next is to create our cards in the database. We have one deck of cards so it's pretty simple.
<pre>
// Create cards
$cards = array ();
foreach ( $this->colors as $color_id => $color ) {
// spade, heart, diamond, club
for ($value = 2; $value <= 14; $value ++) {
// 2, 3, 4, ... K, A
$cards [] = array ('type' => $color_id,'type_arg' => $value,'nbr' => 1 );
}
}

$this->cards->createCards( $cards, 'deck' );
</pre>

This code that will create one of each card. But don't run it yet, because we missing $this->colors.
So we have state of the game in the database, but there is some static game information which never changes.
This information should be stored in material.inc.php and this way it can be accessed from all .php files (and .js if you send it via getAllDatas()).
We will edit this file now by adding these lines

<pre>
$this->colors = array(
1 => array( 'name' => clienttranslate('spade'),
'nametr' => $this->_('spade') ),
2 => array( 'name' => clienttranslate('heart'),
'nametr' => $this->_('heart') ),
3 => array( 'name' => clienttranslate('club'),
'nametr' => $this->_('club') ),
4 => array( 'name' => clienttranslate('diamond'),
'nametr' => $this->_('diamond') )
);

$this->values_label = array(
2 =>'2',
3 => '3',
4 => '4',
5 => '5',
6 => '6',
7 => '7',
8 => '8',
9 => '9',
10 => '10',
11 => clienttranslate('J'),
12 => clienttranslate('Q'),
13 => clienttranslate('K'),
14 => clienttranslate('A')
);
</pre>

Where $this->colors will define Suit labels and $this->values_label will define value labels.
If you noticed, we have two of each label for suits. This is because sometimes we need translated values on the php
side and sometimes we don't. In this case '''nametr''' will return a translated value in php, which is only useful when you throw exceptions to show the right strings. If you pass a value to the client via notification you should always use untranslated strings, and the client will translate it. 'clienttranslate' marks the value for translation but does not actually change it for php. For more about this wonderful translation stuff see [[Translations]].

== Full game model synchronisation ==

Now at any point in the game we need to make sure that database information can be reflected back in the UI, so we must fix the '''getAllDatas''' function
to return all possible data we need to reconstruct the game. This is in the game.php file. The template for getAllDatas() already takes care of player info. Let's just
add hand and tableau data before we return a result.

<pre>
// Cards in player hand
$result['hand'] = $this->cards->getCardsInLocation( 'hand', $current_player_id );

// Cards played on the table
$result['cardsontable'] = $this->cards->getCardsInLocation( 'cardsontable' );
</pre>

Now on the client side we should display this data, so in your .js file in the setup function (which is the receiver of getAllDatas) replace our hack of putting 5 of Hearts directly into the hand with:

<pre>
// Cards in player's hand
for ( var i in this.gamedatas.hand) {
var card = this.gamedatas.hand[i];
var color = card.type;
var value = card.type_arg;
this.playerHand.addToStockWithId(this.getCardUniqueId(color, value), card.id);
}

// Cards played on table
for (i in this.gamedatas.cardsontable) {
var card = this.gamedatas.cardsontable[i];
var color = card.type;
var value = card.type_arg;
var player_id = card.location_arg;
this.playCardOnTable(player_id, color, value, card.id);
}
</pre>

This should show hand and tableau cards now, except we are missing the '''playCardOnTable''' function. So find the '''getCardUniqueId''' function which
should be in the utilities section and add this after it:

<pre>
playCardOnTable : function(player_id, color, value, card_id) {
// player_id => direction
this.addTableCard(value, color, player_id, player_id);

if (player_id != this.player_id) {
// Some opponent played a card
// Move card from player panel
this.placeOnObject('cardontable_' + player_id, 'overall_player_board_' + player_id);
} else {
// You played a card. If it exists in your hand, move card from there and remove
// corresponding item

if ($('myhand_item_' + card_id)) {
this.placeOnObject('cardontable_' + player_id, 'myhand_item_' + card_id);
this.playerHand.removeFromStockById(card_id);
}
}

// In any case: move it to its final destination
this.slideToObject('cardontable_' + player_id, 'playertablecard_' + player_id).play();
},
</pre>

For this to work we also need to define the addTableCard
<pre>
addTableCard(value, color, card_player_id, playerTableId) {
const x = value - 2;
const y = color - 1;
document.getElementById('playertablecard_' + playerTableId).insertAdjacentHTML('beforeend', `
<div class="card cardontable" id="cardontable_${card_player_id}" style="background-position:-${x}00% -${y}00%"></div>
`);
},
</pre>

What this does is basically create another card object, because if it is not our card it's not in our hand (Stock) so
we have to create it out of thin air. The technique to do that is to implement a Javascript template object defined in the .tpl file with some
parameters, which will basically create a "div" string (yes you could have used string concatenation but it would not be fancy).
Now dojo.place places it (the div) on top of a placeholder. Now we have an object with an id of 'cardontable_' + player_id. Depending
on who is playing it we either place it on the player miniboard or in hand (and remove it from hand stock). Then we animate the card move.

We also should fix our .css file now to add style for cardontable and REMOVE background for playertablecard which really is a placeholder div and not a card. (Don't miss the remove step; it will be all screwy if you do!)

<pre>
.playertablecard {
display: inline-block;
position: relative;
margin-top: 5px;
width: 72px;
height: 96px;
/* we remove background-image here */
}

/*** cards on table ***/

.cardontable {
position: absolute;
width: 72px;
height: 96px;
background-image: url('img/cards.jpg');
}
</pre>

Now to test that it actually works let's deal cards to players during game initialization:

Add this after createCards in setupNewGame function in the game.php file
<pre>
// Shuffle deck
$this->cards->shuffle('deck');
// Deal 13 cards to each players
$players = $this->loadPlayersBasicInfos();
foreach ( $players as $player_id => $player ) {
$cards = $this->cards->pickCards(13, 'deck', $player_id);
}
</pre>

Now when you start the game you should see 13 cards in your hand!

We just need to hook-up clicking on card and test if our playCardOnTable works.

Find onPlayerHandSelectionChanged function in the JS file, we should have logging there like console.log("on playCard "+card_id);
So after that insert this (Note: this code is for testing we will replace it with server interaction after we test it.):
<pre>
console.log("on playCard "+card_id);
// type is (color - 1) * 13 + (value - 2)
var type = items[0].type;
var color = Math.floor(type / 13) + 1;
var value = type % 13 + 2;

this.playCardOnTable(this.player_id,color,value,card_id);
</pre>
Now if you force reload (because we changed .css before) you should be able to click on card from your hand and see it moving,
you can click on few cards this way. When you done enjoying the animation, press F5 to get your hand back.

[[File:Heartsla-sync.png]]

Code Rev [https://github.com/elaskavaia/bga-heartsla/tree/01d4e2f595fd14c2adcc97a957d21bb2766f78a8]

== State Machine ==

Now we need to create a game state machine. So the states are (excluding two more states we will add later to handle the exchange of cards at the beginning of the rounds):

* Cards are dealt to all players (lets call it "newHand")
* Player is selected who will start a new trick ("newTrick")
* Player start or respond to played card ("playerTurn")
* Game control is passed to next player or trick is ended ("nextPlayer")
* End of hand processing (scoring and check for end of game) ("nextHand")

The state handling spread across 4 files, so you have to make sure all pieces are connected together.
The state machine states.php defines all the states, and function handlers on php side in a form of string,
and if any of these functions are not implemented it would be very hard to debug because it will break in random places.

So .states.php

<pre>
$machinestates = array(

// The initial state. Please do not modify.
1 => array(
"name" => "gameSetup",
"description" => clienttranslate("Game setup"),
"type" => "manager",
"action" => "stGameSetup",
"transitions" => array( "" => 2 )
),

/// New hand
2 => array(
"name" => "newHand",
"description" => "",
"type" => "game",
"action" => "stNewHand",
"updateGameProgression" => true,
"transitions" => array( "" => 30 )
),

21 => array(
"name" => "giveCards",
"description" => clienttranslate('Some players must choose 3 cards to give to ${direction}'),
"descriptionmyturn" => clienttranslate('${you} must choose 3 cards to give to ${direction}'),
"type" => "multipleactiveplayer",
"action" => "stGiveCards",
"args" => "argGiveCards",
"possibleactions" => array( "actGiveCards" ),
"transitions" => array( "giveCards" => 22, "skip" => 22 )
),

22 => array(
"name" => "takeCards",
"description" => "",
"type" => "game",
"action" => "stTakeCards",
"transitions" => array( "startHand" => 30, "skip" => 30 )
),

// Trick

30 => array(
"name" => "newTrick",
"description" => "",
"type" => "game",
"action" => "stNewTrick",
"transitions" => array( "" => 31 )
),
31 => array(
"name" => "playerTurn",
"description" => clienttranslate('${actplayer} must play a card'),
"descriptionmyturn" => clienttranslate('${you} must play a card'),
"type" => "activeplayer",
"possibleactions" => array( "actPlayCard" ),
"transitions" => array( "playCard" => 32 )
),
32 => array(
"name" => "nextPlayer",
"description" => "",
"type" => "game",
"action" => "stNextPlayer",
"transitions" => array( "nextPlayer" => 31, "nextTrick" => 30, "endHand" => 40 )
),

// End of the hand (scoring, etc...)
40 => array(
"name" => "endHand",
"description" => "",
"type" => "game",
"action" => "stEndHand",
"transitions" => array( "nextHand" => 2, "endGame" => 99 )
),

// Final state.
// Please do not modify.
99 => array(
"name" => "gameEnd",
"description" => clienttranslate("End of game"),
"type" => "manager",
"action" => "stGameEnd",
"args" => "argGameEnd"
)

);
</pre>

The full details on these fields are in [[Your_game_state_machine:_states.inc.php]].

But basically we have Player states, in which a human player has to perform an "action" by pressing some button in the UI or selecting some game item, which will trigger js handler, which will do an ajax call to the server.

To make it run we have to define all the handler functions that we referenced in states, which are - one function for state arguments argGiveCards, 4 functions for robot states (where the game performs some action)
and 1 function for player actions handling.
In .game.php, find 'Game state arguments' section and paste this in:
<pre>
function argGiveCards() {
return array ();
}
</pre>

This normally passes some parameters to states, but we don't need anything yet. It's good to have a placeholder there anyway, so we can fix it later.
Important: even when it's a stub, this function must return an array not a scalar.

Let's do stubs for other functions, find the game state actions section in .game.php file and insert these
<pre>
function stNewHand() {
// Take back all cards (from any location => null) to deck
$this->cards->moveAllCardsInLocation(null, "deck");
$this->cards->shuffle('deck');
// Deal 13 cards to each players
// Create deck, shuffle it and give 13 initial cards
$players = $this->loadPlayersBasicInfos();
foreach ( $players as $player_id => $player ) {
$cards = $this->cards->pickCards(13, 'deck', $player_id);
// Notify player about his cards
$this->notifyPlayer($player_id, 'newHand', '', array ('cards' => $cards ));
}
$this->setGameStateValue('alreadyPlayedHearts', 0);
$this->gamestate->nextState("");
}

function stNewTrick() {
// New trick: active the player who wins the last trick, or the player who own the club-2 card
// Reset trick color to 0 (= no color)
$this->setGameStateInitialValue('trickColor', 0);
$this->gamestate->nextState();
}

function stNextPlayer() {
// Active next player OR end the trick and go to the next trick OR end the hand
if ($this->cards->countCardInLocation('cardsontable') == 4) {
// This is the end of the trick
// Move all cards to "cardswon" of the given player
$best_value_player_id = $this->activeNextPlayer(); // TODO figure out winner of trick
$this->cards->moveAllCardsInLocation('cardsontable', 'cardswon', null, $best_value_player_id);

if ($this->cards->countCardInLocation('hand') == 0) {
// End of the hand
$this->gamestate->nextState("endHand");
} else {
// End of the trick
$this->gamestate->nextState("nextTrick");
}
} else {
// Standard case (not the end of the trick)
// => just active the next player
$player_id = $this->activeNextPlayer();
$this->giveExtraTime($player_id);
$this->gamestate->nextState('nextPlayer');
}
}

function stEndHand() {
$this->gamestate->nextState("nextHand");
}

</pre>
Important: All state actions game or player must end with state transition (or thrown exception). Also make sure it's ONLY one state transition,
if you accidentally fall through after state transition and do another one it will be a real mess and head scratching for long time.

Now find 'player actions' section and paste this code there
<pre>
function actPlayCard(int $card_id) {
$player_id = $this->getActivePlayerId();
throw new BgaUserException($this->_("Not implemented: ") . "$player_id plays $card_id");
}
</pre>
We won't implement it yet but throw an exception which we will see if interaction is working properly

Now the game should start but it would not be any different than before because we have to implement actual interactions.
It's good to check if it's still working though (and if it was running before you have to exit because we changed state machine and normally it will break stuff). NOTE: When you play a card, you will not yet get the "Not implemented" message. That is added in the next section.

== Client - Server interactions ==

Now to implement things for real we have hook UI actions to ajax calls, and process notifications sent by the server.
So previously we hooked playCardOnTable right into js handler which caused client animation, in real game its a two
step operation. When user clicks on game element js client sends an ajax call to server, server processes it and updates database, server sends
notification in response, client hooks animations to server notification.

So in .js code replace onPlayerHandSelectionChanged with
<pre>
onPlayerHandSelectionChanged : function() {
var items = this.playerHand.getSelectedItems();

if (items.length > 0) {
var action = 'actPlayCard';
if (this.checkAction(action, true)) {
// Can play a card
var card_id = items[0].id;
this.bgaPerformAction(action, {
card_id : card_id,
});

this.playerHand.unselectAll();
} else if (this.checkAction('actGiveCards')) {
// Can give cards => let the player select some cards
} else {
this.playerHand.unselectAll();
}
}
},
</pre>

Now when you click on card you should get a server response: Not implemented...

Lets implement it, in .game.php
<pre>
function actPlayCard(int $card_id) {
$player_id = $this->getActivePlayerId();
$this->cards->moveCard($card_id, 'cardsontable', $player_id);
// XXX check rules here
$currentCard = $this->cards->getCard($card_id);
// And notify
$this->notifyAllPlayers('playCard', clienttranslate('${player_name} plays ${value_displayed} ${color_displayed}'), array (
'i18n' => array ('color_displayed','value_displayed' ),'card_id' => $card_id,'player_id' => $player_id,
'player_name' => $this->getActivePlayerName(),'value' => $currentCard ['type_arg'],
'value_displayed' => $this->values_label [$currentCard ['type_arg']],'color' => $currentCard ['type'],
'color_displayed' => $this->colors [$currentCard ['type']] ['name'] ));
// Next player
$this->gamestate->nextState('playCard');
}
</pre>

We get the card from client, we move it to the table (moveCard is hooked to database directly, its part of deck class),
we notify all players and we change state. What we are missing here is bunch of checks (rule enforcements), we will add it later.

Interesting part about this notify is that we use i18n array for strings that needs to be translated by client, so
they are sent as English text in notification, then client has to know which parameters needs translating.

On the client side .js we have to implement a notification handler to do the animation

<pre>
setupNotifications : function() {
console.log('notifications subscriptions setup');

const notifs = [
['newHand', 1],
['playCard', 100],
];

notifs.forEach((notif) => {
dojo.subscribe(notif[0], this, `notif_${notif[0]}`);
this.notifqueue.setSynchronous(notif[0], notif[1]);
});

},

notif_newHand : function(notif) {
// We received a new full hand of 13 cards.
this.playerHand.removeAll();

for ( var i in notif.args.cards) {
var card = notif.args.cards[i];
var color = card.type;
var value = card.type_arg;
this.playerHand.addToStockWithId(this.getCardUniqueId(color, value), card.id);
}
},

notif_playCard : function(notif) {
// Play a card on the table
this.playCardOnTable(notif.args.player_id, notif.args.color, notif.args.value, notif.args.card_id);
},
</pre>

Now it actually works through the server when you click on card - the move is recorded. If you test it now you will notice
after trick is done all cards remains on the table, but if you press F5 they would disappear, this is because
we updated database to pick-up the cards but did not send notification about it, so we need to send notification about it
and have a handler for it

So in .game.php file add notification in stNextPlayer function after moveAllCardsInLocation call:

<pre>
// Notify
// Note: we use 2 notifications here in order we can pause the display during the first notification
// before we move all cards to the winner (during the second)
$players = $this->loadPlayersBasicInfos();
$this->notifyAllPlayers( 'trickWin', clienttranslate('${player_name} wins the trick'), array(
'player_id' => $best_value_player_id,
'player_name' => $players[ $best_value_player_id ]['player_name']
) );
$this->notifyAllPlayers( 'giveAllCardsToPlayer','', array(
'player_id' => $best_value_player_id
) );
</pre>

And in .js file add 2 more notification handlers.

This is to subscribe in setupNotifications function
<pre>
const notifs = [
...
['trickWin', 1000],
['giveAllCardsToPlayer', 600],
];
</pre>

And these are handlers
<pre>
notif_trickWin : function(notif) {
// We do nothing here (just wait in order players can view the 4 cards played before they're gone.
},
notif_giveAllCardsToPlayer : function(notif) {
// Move all cards on table to given table, then destroy them
var winner_id = notif.args.player_id;
for ( var player_id in this.gamedatas.players) {
var anim = this.slideToObject('cardontable_' + player_id, 'overall_player_board_' + winner_id);
dojo.connect(anim, 'onEnd', function(node) {
dojo.destroy(node);
});
anim.play();
}
},
</pre>

So 'trickWin' notification does not do much except it will delay the processing of next notification by 1 second (1000 ms)
and it will log the message (that happens independently of what handler does).
<i>Note: if on the other hand you don't want to log but want to do something else, send an empty message</i>

Now after the trick you see all cards move towards the "player's stash".

== Scoring and End of game handling ==

Now we should calculate scoring and for that we need to actually track who wins the trick.
Trick is won by the player with highest card (no trump). We just need to remember what is trick suite.
For which we will use state variable 'trickColor' which we already conveniently created.

In .game.php file find the playCard function and add this before notify functions
$currentTrickColor = $this->getGameStateValue( 'trickColor' ) ;
if( $currentTrickColor == 0 )
$this->setGameStateValue( 'trickColor', $currentCard['type'] );

This will make sure we remember the first suit being played, now to use it modify the stNextPlayer function to fix our TODO comment
<pre>
function stNextPlayer() {
// Active next player OR end the trick and go to the next trick OR end the hand
if ($this->cards->countCardInLocation('cardsontable') == 4) {
// This is the end of the trick
$cards_on_table = $this->cards->getCardsInLocation('cardsontable');
$best_value = 0;
$best_value_player_id = null;
$currentTrickColor = $this->getGameStateValue('trickColor');
foreach ( $cards_on_table as $card ) {
// Note: type = card color
if ($card ['type'] == $currentTrickColor) {
if ($best_value_player_id === null || $card ['type_arg'] > $best_value) {
$best_value_player_id = $card ['location_arg']; // Note: location_arg = player who played this card on table
$best_value = $card ['type_arg']; // Note: type_arg = value of the card
}
}
}

// Active this player => he's the one who starts the next trick
$this->gamestate->changeActivePlayer( $best_value_player_id );

// Move all cards to "cardswon" of the given player
$this->cards->moveAllCardsInLocation('cardsontable', 'cardswon', null, $best_value_player_id);

// Notify
// ... same code here as before
</pre>

The scoring rule in the studio example code is huge multi-page function, for this tutorial we will make simplier.
Lets score -1 point per heart and call it a day. And game will end when somebody goes -100 or below.

As UI goes for scoring, the main thing to update is the scoring on the mini boards represented by stars, also
we want to show that in the log.
In addition scoring can be shown in [[Game_interface_logic:_yourgamename.js#Scoring_dialogs|Scoring Dialog]] using tableWindow notification, but it is a tutorial on its own and you can do it as homework (it is part of original heart game).

In .js file we need to add one more subscription and notification handler:
const notifs = [
...
['newScores', 1],
];
in setupNotifications

and
notif_newScores : function(notif) {
// Update players' scores
for ( var player_id in notif.args.newScores) {
this.scoreCtrl[player_id].toValue(notif.args.newScores[player_id]);
}
},
somewhere after. this.scoreCtrl is pre-existing object that shows the scoring and this function will update score values per player from notification argument

so in .game.php our stEndHand function will look like

<pre>
function stEndHand() {
// Count and score points, then end the game or go to the next hand.
$players = $this->loadPlayersBasicInfos();
// Gets all "hearts" + queen of spades

$player_to_points = array ();
foreach ( $players as $player_id => $player ) {
$player_to_points [$player_id] = 0;
}
$cards = $this->cards->getCardsInLocation("cardswon");
foreach ( $cards as $card ) {
$player_id = $card ['location_arg'];
// Note: 2 = heart
if ($card ['type'] == 2) {
$player_to_points [$player_id] ++;
}
}
// Apply scores to player
foreach ( $player_to_points as $player_id => $points ) {
if ($points != 0) {
$sql = "UPDATE player SET player_score=player_score-$points WHERE player_id='$player_id'";
$this->DbQuery($sql);
$heart_number = $player_to_points [$player_id];
$this->notifyAllPlayers("points", clienttranslate('${player_name} gets ${nbr} hearts and looses ${nbr} points'), array (
'player_id' => $player_id,'player_name' => $players [$player_id] ['player_name'],
'nbr' => $heart_number ));
} else {
// No point lost (just notify)
$this->notifyAllPlayers("points", clienttranslate('${player_name} did not get any hearts'), array (
'player_id' => $player_id,'player_name' => $players [$player_id] ['player_name'] ));
}
}
$newScores = $this->getCollectionFromDb("SELECT player_id, player_score FROM player", true );
$this->notifyAllPlayers( "newScores", '', array( 'newScores' => $newScores ) );

///// Test if this is the end of the game
foreach ( $newScores as $player_id => $score ) {
if ($score <= -100) {
// Trigger the end of the game !
$this->gamestate->nextState("endGame");
return;
}
}

$this->gamestate->nextState("nextHand");
}
</pre>

So it should more less work now, including end of game condition. Try to play it!

== Additional stuff ==

The following things were not implemented and can add them yourself by looking at the code of original hearts game:

* Remove debug code from setupNewGame to deal cards, cards are now dealt in stNewHand state handler
* Rule checking and rule enforcements in playCard function
* Start scoring with 100 points each and end when <= 0
* Fix scoring rules with Q of spades and 26 point reverse scoring
* First player one with 2 club
* Add progress handling
* Add statistics
* Add card exchange states
* Add game option to start with 75 points instead of 100

[[Category:Studio]]

Game interface logic: Game.js

2024-09-25T18:27:22Z

Sguzzer Gunayer: /* Counters */

{{Studio_Framework_Navigation}}

__TOC__

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

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

== File structure ==

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

Here is the basic structure:

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

More details:

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

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

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

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

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

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

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

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

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

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

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

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

== Dojo framework ==

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

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

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

== Javascript minimization (after July 2020) ==

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

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

== Accessing Players Information ==

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

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

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

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

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

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

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

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

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

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

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

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

== Accessing and manipulating the DOM ==

=== Element by Id ===

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

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

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

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

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

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

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

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

=== Style ===

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

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

Examples:

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

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

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

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

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

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

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

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

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

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

=== Classes ===

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

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

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

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

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

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

Example from ''Reversi'':

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

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

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

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

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

'''Vanilla JS classList'''

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

=== Attributes ===

;dojo.attr

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

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

'''Vanilla JS attr'''

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

=== Queries ===

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

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

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

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

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

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

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

'''Vanilla JS query'''

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

=== Creating and Destroying elements ===

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

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

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

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

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

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

Create element

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

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

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

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

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

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

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

const div = ``;
'''this.format_string_recursive'''

This bga function is similar to this.format_string but is capable of processing recursive argument structures and translations. It is used to format server notifications.

TODO: find better place for these function docs

=== Moving elements ===

'''dojo.place(node: string | Element, refNode: ElementOrId, pos?: string | number): Element'''

dojo.place is the best function to insert HTML code somewhere in your game interface without breaking something. It is much better to use than the '''innerHTML=''' method if you must insert HTML tags and not only values.

node: can be a string or a DOM node. If it is a string starting with “<”, it is assumed to be an HTML fragment, which will be created. Otherwise it is assumed to be an id of a DOM node.

<pre>
// Insert your HTML code as a child of a container element
dojo.place( "<div class='foo'></div>", "your_container_element_id" );
</pre>

pos: optional argument. Can be a number or one of the following strings: “before”, “after”, “replace”, “only”, “first”, or “last”. If omitted, “last” is assumed.

* "replace": replace the container element with my_node element
* "first": places the node as a child of the reference node. The node is placed as the first child.
* "last" (default): places the node as a child of the reference node. The node is placed as the last child.
* "before": places the node right before the reference node.
* "after": places the node right after the reference node.
* "only": replaces all children of the reference node with the node.

this parameter can be a positive integer. In this case, the node will be placed as a child of the reference node with this number (counting from 0). If the number is more than number of children, the node will be appended to the reference node making it the last child.

<pre>
// Replace all children of container with my_node
dojo.place( $('my_node'), "your_container_element_id", "only" );
</pre>

See also full doc on dojo.place: [https://dojotoolkit.org/reference-guide/1.7/dojo/place.html]

Usually, when you want to insert some piece of HTML in your game interface, you should use "[[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl#Javascript_templates|Javascript templates]]".

But you can also relocate elements like that. Note: it won't animate if you do that.

'''this.placeOnObject(mobile_obj: ElementOrId, target_obj: ElementOrId): void'''

places mobile_obj on target_obj, set the absolute positions and centers the mobile_obj on target_obj,
effect is immediate

This is not really an animation, but placeOnObject is frequently used before starting an animation.

Example:
<pre>
// (We just created an object "my_new_token")

// Place the new token on current player board
this.placeOnObject( "my_new_token", "overall_player_board_"+this.player_id );

// Then slide it to its position on the board
this.slideToObject( "my_new_token", "a_place_on_board" ).play();
</pre>

'''this.placeOnObjectPos(mobile_obj: ElementOrId, target_obj: ElementOrId, target_x: number, target_y: number): void'''

This method works exactly like placeOnObject, except than you can specify some (x,y) coordinates (in px). This way, the center of "mobile_obj" will be placed to the specified x,y position relatively to the center of "target_obj".

''Note: the placement works differently from this.slideToObjectPos'', since coordinates are calculated based on the center of objects.

'''this.attachToNewParent(mobile_obj: ElementOrId, target_obj: ElementOrId): void'''

With this method, you change the HTML parent of "mobile_obj" element without moving it.
"target_obj" is the new parent of this element. The beauty of
attachToNewParent is that the mobile_obj element DOES NOT MOVE during this process.

What happens is that the method calculate a relative position of mobile_obj to make sure it does not move after the HTML parent changes.

Why using this method?

Changing the HTML parent of an element can be useful for the following reasons:
* When the HTML parent moves, all its child are moving with them. If some game elements is no more linked with a parent HTML object, you may want to attach it to another place.
* The z_order (vertical order of display) depends on the position in the DOM, so you may need to change the parent of some game elements when they are moving in your game area.

'''CAREFUL''': this function destroys original object and places a clone onto a new parent, this will break all references to this HTML element (ex: dojo.connect).
If you need version that does not destroy the object but the same otherwise see [[BGA_Studio_Cookbook#Attach_to_new_parent_without_destroying_the_object]]

== Animations ==

===Dojo Animations===

BGA animations is based on Dojo Animation ([http://dojotoolkit.org/documentation/tutorials/1.8/animation/ see tutorial here]).

However, most of the time, you can just use methods below, which are built on top of Dojo Animation.

Note: one interesting method from Dojo that could be useful from time to time is "Dojo.Animation". It allows you to make any CSS property "slide" from one value to another.

Note 2: the slideTo methods are not compatible with CSS transform (scale, zoom, rotate...). If possible, avoid using CSS transform on nodes that are being slided. Eventually, the only possible solution to make these 2 compatible is to disable all CSS transform properties, use slideToObjectPos/placeOnObjectPos, and then apply them again.

===Sliding===

'''this.slideToObject(mobile_obj: ElementOrId, target_obj: ElementOrId, duration?: number, delay?: number): Animation'''

You can use slideToObject to "slide" an element to a target position.

Sliding element on the game area is the recommended and the most used way to animate your game interface. Using slides allow players to figure out what is happening on the game, as if they were playing with the real boardgame.

The parameters are:
* mobile_obj: the ID of the object to move. This object must be "relative" or "absolute" positioned.
* target_obj: the ID of the target object. This object must be "relative" or "absolute" positioned. Note that it is not mandatory that mobile_obj and target_obj have the same size. If their size are different, the system slides the center of mobile_obj to the center of target_obj.
* duration: (optional) defines the duration in millisecond of the slide. The default is 500 milliseconds.
* delay: (optional). If you defines a delay, the slide will start only after this delay. This is particularly useful when you want to slide several object from the same position to the same position: you can give a 0ms delay to the first object, a 100ms delay to the second one, a 200ms delay to the third one, ... this way they won't be superposed during the slide.

BE CAREFUL: The method returns an dojo.fx animation, so you can combine it with other animation if you want to. It means that you have to call the "play()" method, otherwise the animation WON'T START.

Example:
<pre>
this.slideToObject( "some_token", "some_place_on_board" ).play();
</pre>

'''this.slideToObjectPos(mobile_obj: ElementOrId, target_obj: ElementOrId, target_x: number, target_y: number, duration?: number, delay?: number): Animation'''

This method does exactly the same as "slideToObject", except than you can specify some (x,y) coordinates. This way, "mobile_obj" will slide to the specified x,y position relatively to "target_obj".

Example: slide a token to some place on the board, 10 pixels from the top:
<pre>
this.slideToObjectPos( "some_token", "some_place_on_board", 0, 10 ).play();
</pre>

'''this.slideTemporaryObject(mobile_obj_html: string, parent: ElementOrId, from: ElementOrId, to: ElementOrId, duration?: number, delay?: number): Animation'''

This method is useful when you want to slide a temporary HTML object from one place to another. As this object does not exists before the animation and won't remain after, it could be complex to create this object (with dojo.place), to place it at its origin (with placeOnObject) to slide it (with slideToObject) and to make it disappear at the end.

slideTemporaryObject does all of this for you:
* mobile_obj_html is a piece of HTML code that represent the object to slide.
* parent is the ID of an HTML element of your interface that will be the parent of this temporary HTML object.
* from is the ID of the origin of the slide.
* to is the ID of the target of the slide.
* duration/delay works exactly like in "slideToObject"

Example:
<pre>
this.slideTemporaryObject( '<div class="token_icon"></div>', 'tokens', 'my_origin_div', 'my_target_div' ).play();
</pre>

===Destroy===
'''this.slideToObjectAndDestroy(mobile_obj: ElementOrId, target_obj: ElementOrId, duration?: number, delay?: number): void'''

This method is a handy shortcut to slide an existing HTML object to some place then destroy it upon arrival. It can be used for example to move a victory token or a card from the board to the player panel to show that the player earns it, then destroy it when we don't need to keep it visible on the player panel.

It works the same as this.slideToObject and takes the same arguments, but it starts the animation.

CAREFUL: Make sure nothing is creating the same object at the same time the animation is running, because this will cause some random disappearing effects

Example:
<pre>
this.slideToObjectAndDestroy( "some_token", "some_place_on_board", 1000, 0 );
</pre>

'''this.fadeOutAndDestroy( node: string | Element, duration?: number, delay?: number):''' '''void'''

This function fade out the target node, then destroy it. Its starts the animation.
* duration/delay works exactly like in "slideToObject"

Example:
<pre>
this.fadeOutAndDestroy( "a_card_that_must_disappear" );
</pre>

CAREFUL: the HTML node still exists until during few milliseconds, until the fadeOut has been completed.
Make sure nothing is creating same object at the same time as animation is running, because you will be some random dissapearing effects

===Rotating elements===

This example combines "Dojo.Animation" method and a CSS property transform that allow you to rotate the element.
<pre>
// node is Element we rotating
var animation = new dojo.Animation({
curve: [fromDegree, toDegree],
onAnimate: (v) => {
node.style.transform = 'rotate(' + v + 'deg)';
}
});

animation.play();
</pre>

BGA has its own interface to rotate

'''this.rotateTo(node: string | Element, degree: number): void'''

It starts the animation, and stored the rotation degree in the class, so next time you rotate object - it is additive.
There is no animation hooks in this one, if you need to change any parameters use dojo animation above.

There is also '''rotateInstantTo''' with same signature which does not animate

===Animation Callbacks===

If you wish to run some code only after an animation has completed you can do this by linking a callback method to 'onEnd'.

<pre>
var animation_id = this.slideToObject( mobile_obj, target_obj, 500 );
dojo.connect(animation_id, 'onEnd', () => {
// do something here
});
animation_id.play();
</pre>

If you wish to call a second animation after the first (rather than general code) then you can use a dojo animation chain (see tutorial referenced above).

== Players input ==

=== Connecting ===
'''dojo.connect(element: Element, event: string, context: object, method: eventHandler): any'''

'''dojo.connect(element: Element, event: string, handler: eventHandler): any'''

Used to associate a player event with one of your notification methods.

Example: associate a click on an element ("my_element") with one of our methods ("onClickOnMyElement"):
<pre>
dojo.connect( $('my_element'), 'onclick', this, 'onClickOnMyElement' );
</pre>

Same idea but based on query (i.e. all element of 'pet' class)
dojo.query(".pet").connect('onclick', this, 'onPet');

Note: if you need to disconnect the handler you have to store handler returned from this method, i.e.

<pre>
var handler = dojo.connect(...);
...
dojo.disconnect(handler);
</pre>

If you don't store the handler - you have to destroy the object to disconnect it

Typical function that implements the input handler will look like this

<pre>
onPet: function(event) {
var id = event.currentTarget.id;
console.log('onPet ' + id);
dojo.stopEvent(event);
if (this.gamedatas.gamestate.name == 'playerTurnPet') {
this.bgaPerformAction('actPlayPet', {card: id});
} else {
this.showMoveUnauthorized();
}
}
</pre>

'''this.connect(element: ElementOrId, event: string, method: eventHandler): void'''

Used to associate a player event with one of your notification methods.

this.connect( $('my_element'), 'onclick', 'onClickOnMyElement' );

Or you can use an in-place handler

this.connect( $('my_element'), 'onclick', (e) => { console.log('boo'); } );

Note that this function stores the connection handler. That is the only real difference between '''this.connect''' and '''dojo.connect'''. If you plan to destroy the element you connected, you '''must''' call this.disconnect() to prevent memory leaks.
This function is mainly for permanent objects - if you just want to connect the temp object you should probably not use this method but use dojo.connect which won't require any clean-up.

'''this.connectClass(cssClassName: string, event: string, method: eventHandler): void'''

Same as connect(), but for all the nodes set with the specified cssClassName.
this.connectClass('pet', 'onclick', 'onPet');
'''this.disconnect(element: ElementOrId, event: string): void'''

Disconnect event handler (previously registered with this.connect or this.connectClass).

this.disconnect( $('my_element'), 'onclick');

Note: dynamic connect/disconnect is for advanced cases ONLY, you should always connect elements statically if possible, i.e. in setup() method.

'''this.disconnectAll(): void'''

Disconnect all previously registed event handlers (registered via this.connect or this.connectClass)

this.disconnectAll();

=== Actions ===

'''this.bgaPerformAction(action: string, args?: object, options: object = { lock: true, checkAction: true }): Promise<void>'''

Triggers an action on the backend. This is a combination of checkAction and ajaxcall, returning a Promise which resoves when ajaxcall ends.

This method must be used to send a player input to the game server. '''It should not be triggered programmatically''', especially not in loops, in callbacks, in notifications, or in onEnteringState/onUpdateActionButtons/onLeavingState, in order not to create race conditions or break replay game and tutorial features. It should be used only in reaction to a user action in the interface.

* action: name of the action, as it is written in "possibleactions" of the current state.
* args: an object containing the call parameters to send to the action
* options: options to tweak the call with some defaults. Default is <code>{ lock: true, checkAction: true }</code>.

Example of a standard call without args:
this.bgaPerformAction('pass');

Example of a standard call with action args:
this.bgaPerformAction('actPlayCard', { id: this.selectedCardId });

Example of a call without checking action (because player is inactive in a multiactive state):

this.bgaPerformAction('actChangeMind', {}, { checkAction: false });

Example of a call without lock (because of a special action not directly related to the game flow):

this.bgaPerformAction('actSetAutoBid', { alwaysBidUntil: 500 }, { lock: false, checkAction: false });

Example of call with reaction to exception:
this.bgaPerformAction('actPlayCard', { id: this.selectedCardId }).catch(()=>{ this.selectedCardId = undefined; });

Example of call with reaction to success:
this.bgaPerformAction('actPlayCard', { id: this.selectedCardId }).then(()=>{ this.unselectAll(); });

'''this.ajaxcall(url, parameters, obj_callback, callback, callback_anycase?, ajax_method?: string)'''

''Note: bgaPerformAction is a simpler way to use ajax calls, ajaxcall stays in the doc for legacy reasons only and should not be used in new projects.''

Same warning as '''this.bgaPerformAction''' about using on user action only.

* url: the url of the action to perform. For a game, it must be: "/<mygame>/<mygame>/myAction.html"
* parameters: an array of parameter to send to the game server.
** Note that "lock: true" must always be specified in this list of parameters in order the interface can be locked during the server call. Cannot use lock: false - to not lock it has to be undefined.
** Note: Restricted parameter names (please don't use them):
*** "action"
*** "module"
*** "class"
* obj_callback: must be set to "this".
* callback (non-optional but rarely used): a function to trigger when the server returns result and everything went fine (not used, as all data handling is done via notifications).
* callback_anycase: (optional) a function to trigger when the server returns ok OR error. If no error this function is called with parameter value false. If an error occurred, the first parameter will be set to true, the second will contain the error message sent by the PHP back-end, and the third will contain an error code.
* ajax_method: (optional and rarely used) if you need to send large amounts of data (over 2048 bytes), you can set this parameter to 'post' (all lower-case) to send a POST request as opposed to the default GET. This works, but was not officially documented, so only use if you really need to.

Usage:
<pre>
this.ajaxcall( '/mygame/mygame/actMyAction.html', { lock: true,
arg1: myarg1,
arg2: myarg2
}, this, (result)=>{} );
</pre>

'''this.checkAction(action: string, nomessage?: boolean): boolean '''

Check if player can do the specified action by taking into account:
* if interface is locked it will return false and show message "An action is already in progress", unless nomessage set to true
* if player is not active it will return false and show message "This is not your turn", unless nomessage set to true
* if action is not in list in possible actions (defined by "possibleaction" in current game state) it will return false and show "This move is not authorized now" error (unconditionally).
* otherwise returns true
Example:
<pre>
function onClickOnGameElement( evt ) {
if( this.checkAction( "actMyAction" ) ) {
// Do the action
}
}
</pre>

'''this.checkPossibleActions(action: string): boolean'''

* this is independent of the player being active, so can be used instead of this.checkAction(). This is particularly useful for multiplayer states when the player is not active in a 'player may like to change their mind' scenario. Unlike this.checkAction, this function does NOT take interface locking into account

* if action is not in list in possible actions (defined by "possibleaction" in current game state) it will return false and show "This move is not authorized now" error (unconditionally).
* otherwise returns true

function onChangeMyMind( evt ) {
if( this.checkPossibleActions( "actMyAction" ) ) {
// Do the action
}
}

'''this.checkLock(nomessage?: boolean): boolean'''

When using "lock: true" in ajax call you can use this function to check if interface is in lock state (it will be locked during server call and notification processing).
This check can be used to block some other interactions which do not result in ajaxcall or if you want to suppress errors. Note: normally you only need to use this.checkAction(...), this is for advanced cases.

It will also show error unless nomessage is set to true

function onChangeMyMind( evt ) {
if( this.checkLock() ) {
// Do the action
}
}

== Notifications ==

When something happens on the server side, your game interface Javascript logic received a notification.
If you have not done so yet check what notification are in [[Main_game_logic:_yourgamename.game.php#Notifications]]

Here's how you can handle these notifications on the client side.

=== Subscribe to notifications ===

'''dojo.subscribe(notif_type: string, callback_obj: Object, handler: string|handler)'''
* notif_type - notification type/name send by php server
* callback_obj - usually this
* handler - if string method of callback_obj with name name is called, when notification is called, with notification object as parameter (see below)

Your Javascript "setupNotifications" method is the place where you can subscribe to notifications from your PHP code.

Here's how you associate one of your Javascript method to a notification "playDisc" (from Reversi example):

<pre>
setupNotifications: function() {
...
dojo.subscribe('playDisc', this, "notif_playDisc");
},
</pre>

Note: the "playDisc" corresponds to the name of the notification you define it in your PHP code, in your "notifyAllPlayers" or "notifyPlayer" method.

Then, you have to define your "notif_playDisc" method:

<pre>
notif_playDisc: function(notif) {
// Remove current possible moves (makes the board more clear)
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );
this.addDiscOnBoard( notif.args.x, notif.args.y, notif.args.player_id );
},
</pre>

In a notification handler like our "notif_playDisc" method, you can access all notifications arguments with "notif.args".

Example:

PHP

<pre>
$this->notifyAllPlayers( "apples", clienttranslate('player takes ${count} apples'), [ "count" => 3 ] );
</pre>

JavaScript

<pre>
setupNotifications: function() {
dojo.subscribe( 'apples', this, 'notif_apples' );
},

notif_apples: function(notif) {
//You can access the "count" like this:
alert("count = " + notif.args.count);
}
</pre>

=== The notification Object received by client ===

When sending a notification on your PHP, the client side will receive an Object with the following attributes:

* type - type of the notification (as passed by php function)
* log - the log string passed from php notification
* args - This is the arguments that you passed on your notification method on php
* bIsTableMsg - is true when you use [[Main_game_logic:_yourgamename.game.php#NotifyAllPlayers|NotifyAllPlayers]] method (false otherwise)
* channelorig - information about table ID (formatted as : "/table/t[TABLE_NUMBER]")
* gamenameorig - name of the game
* move_id - ID of the move associated with the notification
* table_id - ID of the table (comes as string)
* time - UNIX GMT timestamp
* uid - unique identifier of the notification
* h - unknown

'' Note that those information were inferred from observation on console log. If an Admin can confirm/correct (and remove this line), you're welcome :)''

=== Ignoring notifications ===

Sometimes you need to ignore some notification on client side. You don't want them to be shown in game log and you don't want them to be handled.

The most common use case is when a player gets private information. They will receive a specific notification (such as "You received Ace of Heart"), while other players would receive more generic notification ("Player received a card").

In X.game.php
<pre>
$this->notifyAllPlayers("dealCard", clienttranslate('${player_name} received a card'), [
'player_id' => $playerId,
'player_name' => $this->getActivePlayerName()
]);

$this->notifyPlayer($playerId, "dealCardPrivate", clienttranslate('You received ${cardName}'), [
"type" => $card["type"],
"cardName" => $this->getCardName($card["type"])
]);
</pre>

The problem with this approach is that the active player will receive two notifications:
* Player1 received a card
* You received Ace of Hearts

Hence, notification ignoring.

NOTE: You can think that it would be possible to send such notification to all players except active just by using notifyPlayer and it seems to work. The problem however is that table spectators would miss such notification and their user interface (and game log) wouldn't be updated. Since there is no way to send notification just to spectators, ignoring the notification (or "filtering") is the only reasonable solution.

'''setIgnoreNotificationCheck(notif_type: string, predicate: ((notif: Notif)=>boolean))'''

This method will set a check whether any of notifications of specific type should be ignored.

The parameters are:
* notif_type: type of the notification
* predicate (notif => boolean): a function that will receive notif object and will return true if this specific notification should be ignored

Before dispatching any notification of this type, the framework will call predicate to check whether notification should be ignored, if it return true - the notification will be dispatched, i.e. logged or handled.

<pre>
this.notifqueue.setIgnoreNotificationCheck( 'dealCard', (notif) => (notif.args.player_id == this.player_id) );
</pre>

IMPORTANT: Remember that this notification is ignored on the client side, but was still received by the client. Therefore it shouldn't contain any private information as cheaters can get it. In other words this is not a way to hide information.

IMPORTANT: When a game is reloaded with F5 or when opening a turn based game, old notifications are replayed as history notification. They are used just to update the game log and are stripped of all arguments except player_id, i18n and any argument present in message. If you use and other argument in your predicate you should '''preserve''' it as explained [[Main_game_logic:_yourgamename.game.php#Notify_players|here]].

=== Synchronous notifications ===

When several notifications are received by your game interface, these notifications are processed immediately, one after the other, in the same exact order they have been generated in your PHP game logic.

However, sometimes, you need to give some time to the players to figure out what happened on the game before jumping to the next notification. Indeed, in many games, there are a lot of automatic actions, and the computer is going to resolve all these actions very fast if you don't tell it not to do so.

As an example, for Reversi, when someone is playing a disc, we want to wait 500 milliseconds before doing anything else in order the opponent player can figure out what move has been played.

Here's how we do this, right after our subscription:
<pre>
dojo.subscribe( 'playDisc', this, "notif_playDisc" );
this.notifqueue.setSynchronous( 'playDisc', 500 ); // Wait 500 milliseconds after executing the playDisc handler
</pre>

-----

It is also possible to control the delay timing dynamically (e.g., using notification args). As an example, maybe your notification 'cardPlayed' should pause for a different amount of time depending on the number or type of cards played.

For this case, use '''setSynchronous''' without specifying the duration and use '''setSynchronousDuration''' within the notification callback.

* NOTE: If you forget to invoke '''setSynchronousDuration''', the game will remain paused forever!

<pre>
setupNotifications: function () {
dojo.subscribe( 'cardPlayed', this, 'notif_cardPlayed' );
this.notifqueue.setSynchronous( 'cardPlayed' ); // wait time is dynamic
...
},

notif_cardPlayed: function (notif) {
// MUST call setSynchronousDuration

// Example 1: From notification args (PHP)
this.notifqueue.setSynchronousDuration(notif.args.duration);
...

// Or, example 2: Match the duration to a Dojo animation
var anim = dojo.fx.combine([
...
]);
anim.play();
this.notifqueue.setSynchronousDuration(anim.duration);
},
</pre>

You can also manually call this.notifqueue.setSynchronousDuration(0) once client operations are finished, but be careful that even fast replay still has a path to call it.

'''WARNING: combining synchronous and ignored notifications'''
You must be careful when combining dynamic synchronous durations (as described above) with ignored notifications. If you have a conditionally ignored notification like this (see below section):

<pre>this.notifqueue.setIgnoreNotificationCheck( 'myNotif', (notif) => (notif.args.player_id == this.player_id) /* or any other condition */ )</pre>

then you CANNOT do

<pre>this.notifqueue.setSynchronous('myNotif');</pre>

as, when the ignored check passes, the notification handler, in which `this.notifqueue.setSychronousDuration` is called, is never called and so the duration is never set and interface locking results.

The workaround is to set a "dummy" time:

<pre>this.notifqueue.setSynchronous('myNotif', 5000);</pre>

whose value is irrelevant but must be large enough to cover the time before the notification handler is called. The large value never actually comes into play because the notification is either ignored, or the synchronous duration is reset to a sensible value inside the handler.

=== Pre-defined notification types ===

'''tableWindow''' - This defines notification to display [[Game_interface_logic:_yourgamename.js#Scoring_dialogs|Scoring Dialogs]], see below.

'''message''' - This defines notification that shows on players log and have no other effect (technically any unhandled notification will do the same but its recommended to use this keyword for consistency)

// You can call this on php side without doing anything on client side
self::notifyAllPlayers( 'message', clienttranslate('hello'), [] );

'''simplePause''' - This notification will just delay other notifications, maybe useful if you know you need some extra time for animation or something. Requires a time parameter.

<pre>
self::notifyAllPlayers( 'simplePause', '', [ 'time' => 500] ); // time is in milliseconds
</pre>

Note: the following types are RESERVED by framework, do not use:

gameStateChange gameStateChangePrivateArg gameStateMultipleActiveUpdate newActivePlayer playerstatus yourturnack clockalert tableInfosChanged playerEliminated tableDecision archivewaitingdelay end_archivewaitingdelay replaywaitingdelay end_replaywaitingdelay replayinitialwaitingdelay end_replayinitialwaitingdelay aiPlayerWaitingDelay replay_has_ended updateSpectatorList wouldlikethink updateReflexionTime undoRestorePoint resetInterfaceWithAllDatas zombieModeFail zombieModeFailWarning aiError skipTurnOfPlayer zombieBack allPlayersAreZombie gameResultNeutralized playerConcedeGame showTutorial showCursor showCursorClick skipTurnOfPlayerWarning banFromTable resultsAvailable switchToTurnbased newPrivateState infomsg

== Tooltips ==

=== Adding static tooltips ===

'''this.addTooltip(nodeId: string, helpStringTranslated: string, actionStringTranslated: string, delay?: number): void'''

Add a simple text tooltip to the DOM node.

Specify 'helpStringTranslated' to display some information about "what is this game element?".
Specify 'actionStringTranslated' to display some information about "what happens when I click on this element?".

You must specify both of the strings. You can only use one and specify an empty string ('') for the other one.

When you pass text directly function _() must be used for the text to be marked for translation! Except for empty string.

Parameter "delay" is optional. It is primarily used to specify a zero delay for some game element when the tooltip gives really important information for the game - but remember: no essential information must be placed in tooltips as they won't be displayed in some browsers (see [[BGA_Studio_Guidelines|Guidelines]]).

Example:
<pre>
this.addTooltip( 'cardcount', _('Number of cards in hand'), '' );
</pre>

Note: this generates static tooltip and attaches to existing dom element, if you need to generate tooltip more dynamically you have to call that method every time information about object is updated or use completely different tehnique, see dynamic tooltips below.

'''this.addTooltipHtml(nodeId: string, html: string, delay?: number): void'''

Add an HTML tooltip to the DOM node (for more elaborate content such as presenting a bigger version of a card).

'''this.addTooltipToClass(cssClass: string, helpStringTranslated: string, actionStringTranslated: string, delay?: number ): void'''

Add a simple text tooltip to all the DOM nodes set with this cssClass. See more details above for this.addTooltip.
this.addTooltipToClass( 'meeple', _('This is A Meeple'), _('Click to tickle') );

IMPORTANT: all concerned nodes must exist and have IDs to get tooltips.

'''this.addTooltipHtmlToClass(cssClass: string, html: string, delay?: number): void'''

Add an HTML tooltip to to all the DOM nodes set with this cssClass (for more elaborate content such as presenting a bigger version of a card).

IMPORTANT: all concerned nodes must exist and have IDs to get tooltips.

=== Removing static tooltips ===

'''this.removeTooltip(nodeId: string): void'''

Remove a tooltip from the DOM node with given id.

=== Advanced tooltips ===

'''force tooltip to open'''

If you want to force tooltip to open in reaction to some other action, i.e. click you can do this

this.tooltips[id].open(id)

where id is the id of the tooltip node where tooltip was installed.

'''dynamic tooltips'''

See [[BGA_Studio_Cookbook#Dynamic_tooltips]]

'''tooltips on mobile'''

Tooltips is very unreliable on mobile, it is recommended to implement some other method to obtaining same information,
such as simple click handler in dedicated "Help" mode or provide dedicated clickable areas such as corner of card.

== Warning messages ==

Sometimes, there is something important that is happening in the game and you have to make sure all players get the message. Most of the time, the evolution of the game situation or the game log is enough, but sometimes you need something more visible.

Ex: someone fulfills one of the end of the game conditions, so this is the last turn.

'''this.showMessage(msg: string, type: string): void'''

showMessage shows a message in a big rectangular area on the top of the screen of the current player, and it dissapears after few seconds (also it will be in the log in some cases).

* "msg" is the string to display. It should be translated.
* "type" can be set to "info", "error", "only_to_log" or custom string. If set to "info", the message will be an informative message on a white background. If set to "error", the message will be an error message on a red background and it will be added to log. If set to "only_to_log", the message will be added to the game log but will not popup at the top of the screen.
If set to custom string, it will be transparent, to use custom type define "head_xxx" in css, where xxx is the type. For example if you want yellow warning, use "warning" as type and add this to css:
.head_warning {
background-color: #e6c66e;
}

Important: the normal way to inform players about the progression of the game is the game log. The "showMessage" is intrusive and should not be used often.

<pre>
notif_messageinfo: function(notif) {
if (!g_archive_mode) {
var message = this.format_string_recursive(notif.log, notif.args);
this.showMessage(_('Announcement:') + " " + message, 'info');
}
},
</pre>

Show message could be used on the client side to prevent user wrong moves before it is send to server.
Example from 'battleship':
<pre>
onGrid: function(event) {
if (checkIfPlayerTriesToFireOnThemselves(event)) {
this.showMessage(_('This is your own board silly!'), 'error');
return;
}
...
},
</pre>

'''this.showMoveUnauthorized(): void'''

Shows predefined user error that move is unauthorized now

<pre>
onPet: function(event) {
if (checkPet(event)==false) {
this.showMoveUnauthorized();
return;
}
...
},
</pre>

== Dialogs ==

=== Confirmation dialog ===

When an important action with a lot of consequences is triggered by the player, you may want to propose a confirmation dialog.

CAREFUL: the general guideline of BGA is to AVOID the use of confirmation dialogs. Confirmation dialogs slow down the game and bother players. The players know that they have to pay attention to each move when they are playing online.

The situations where you should use a confirmation dialog are the following:
* It must not happen very often during a game.
* It must be linked to an action that can really "kill a game" if the player does not pay attention.
* It must be something that can be done by mistake (ex: a link on the action status bar).

'''this.confirmationDialog(message: string, yesHandler: (param: any) => void, noHandler?: (param: any) => void, param?: any): void'''

* message - message will be shown to user, use _() to translate
* yesHandler - non-optional handler to be called on yes
* noHandler - optional handler to called on no
* param - if specified, it will be passed to both handlers
NOTE: this is async function, it does not return anything and you should not do anything after, you must do everything in handlers

How to display a confirmation dialog:
<pre>
this.confirmationDialog(_("Are you sure you want to bake a pie?"), () => {
this.bakeThePie();
});
return; // nothing should be called or done after calling this, all action must be done in the handler
</pre>
With param and both handlers
<pre>
this.confirmationDialog(_("Are you sure you want to bake a pie?"),
(ingredient) => this.bakeThePie(ingredient),
(ingredient) => console.log(`cancelled baking of ${ingredient}`),
'apple');
</pre>

=== Multiple choice dialog ===

You can use this dialog to give user a choice with small amount of options

'''this.multipleChoiceDialog(message: string, choices: string[], callback: (choice: number) => void): void'''
* message - message will be shown to user, use _() to translate
* choices - array of choices
* callback - non-optional handler to be called on choice made, the choice parameter is the INDEX of the choice from the array of choices

NOTE: this is async function, it does not return anything and you should not do anything after, you must do everything in handlers
NOTE: there is no cancel handler, so make sure you gave user a choice to get out of it

Example:
<pre>
const keys = ["0", "1", "5", "10"];
this.multipleChoiceDialog(_("How many bugs to fix?"), keys, (choice) => {
if (choice==0) return; // cancel operation, do not call server action
var bugchoice = keys[choice]; // choice will be 0,1,2,3 here
this.bgaPerformAction("fixBugs", { number: bugchoice });
});
return; // must return here
</pre>

=== Generic Dialogs ===

As a general rule, you shouldn't use dialogs windows.

BGA guidelines specify that all game elements should be displayed on the main screen. Players can eventually scroll down to see game elements they don't need to see anytime, and you may eventually create anchors to move between game area section. Of course dialogs windows are very practical, but the thing is: all players know how to scroll down, and not all players know how to show up your dialog window. In addition, when the dialog shows up, players can't access the other game components.

Sometimes although, you need to display a dialog window. Here is how you do this:

// Create the new dialog over the play zone. You should store the handler in a member variable to access it later
this.myDlg = new ebg.popindialog();
this.myDlg.create( 'myDialogUniqueId' );
this.myDlg.setTitle( _("my dialog title to translate") );
this.myDlg.setMaxWidth( 500 ); // Optional

// Create the HTML of my dialog.
// The best practice here is to use [[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl#Javascript_templates|Javascript templates]]
var html = this.format_block( 'jstpl_myDialogTemplate', {
arg1: myArg1,
arg2: myArg2,
...
} );

// Show the dialog
this.myDlg.setContent( html ); // Must be set before calling show() so that the size of the content is defined before positioning the dialog
this.myDlg.show();

// Now that the dialog has been displayed, you can connect your method to some dialog elements
// Example, if you have an "OK" button in the HTML of your dialog:
dojo.connect($('my_ok_button'), 'onclick', this, (event) => {
event.preventDefault();
this.myDlg.destroy();
});

If necessary, you can remove the default top right corner 'close' icon, or replace the function called when it is clicked:
// Removes the default close icon
this.myDlg.hideCloseIcon();

// Replace the function call when it's clicked
this.myDlg.replaceCloseCallback((event) => { ... });

=== Scoring dialogs ===

Sometimes at the end of a round you want to display a big table that details the points wins in each section of the game.

Example: in Hearts game, we display at the end of each round the number of "heart" cards collected by each player, the player who collected the Queen of Spades, and the total number of points loose by each player.

Scoring dialogs are managed entirely on '''PHP side''', but they are described here as their effects are visible only on client side.

Displaying a scoring dialog is quite simple and is using a special notification type: "tableWindow":
<pre>
// on PHP side:
$this->notifyAllPlayers( "tableWindow", '', array(
"id" => 'finalScoring',
"title" => clienttranslate("Title of the scoring dialog"),
"table" => $table
));
</pre>

The "table" argument is a 2 dimensional PHP array that describes the table you want to display, line by line and column by column.

Example: display an 3x3 array of strings
<pre>
$table = [
[ "one", "two", "three" ], // This is my first line
[ "four", "five", "six" ], // This is my second line
[ "seven", "height", "nine" ] // This is my third line
];
</pre>

As you can see above, in each "cell" of your array you can display a simple string value. But you can also display a complex value with a template and associated arguments like this:
<pre>
$table = [
[ "one", "two", [ "str" => clienttranslate("a string with an ${argument}"), "args" => [ 'argument' => 'argument_value' ] ] ],
[ "four", "five", "six" ],
[ "seven", "height", "nine" ]
];
</pre>

This is especially useful when you want to display player names with colors. Example from "Hearts":
<pre>
$firstRow = [ '' ];
foreach( $players as $player_id => $player ) {
$cell = [ 'str' => '${player_name}',
'args' => [ 'player_name' => $player['player_name'] ],
'type' => 'header'
];
$firstRow[] = $cell;
}
$table[] = $firstRow;
...
</pre>

You can also use three extra attributes in the parameter array for the notification:
* '''header''': the content for this parameter displays before the table (also, the html will be parsed and player names will be colored according to the current game colors).
* '''footer''': the content for this parameter displays after the table (no parsing for coloring the player names)
* '''closing''': if this parameter is used, a button will be displayed with this label at the bottom of the popup and will allow players to close it (more easily than by clicking the top right 'cross' icon).

<pre>
$this->notifyAllPlayers( "tableWindow", '', [
"id" => 'finalScoring',
"title" => clienttranslate("Title of the scoring dialog"),
"table" => $table,
"header" => ['str' => clienttranslate('Table header with parameter ${number}'),
'args' => [ 'number' => 3 ],
],
"footer" => '<div class="myfoot"></div>',
"closing" => clienttranslate( "Closing button label" )
] );
</pre>

Note: currently id is not used - so you cannot access resulting div by id on js side

Note: any traslatable string have to be wrapped by clienttranslate() on top level OR it has to be recursive template.

DO NOT DO THIS:
<pre>
"footer" => '<div>'.clienttranslate( "The end" ).'</div>', // this will not work for translations!!!
</pre>

=== Scoring animated display ===

Sometimes, you may want to display a score value over an element to make the scoring easier to follow for the players (Terra Mystica final scoring for example).
You can do it with:

'''this.displayScoring(anchor_id: string, color: string, score: number | string, duration?: number, offset_x?: number, offset_y?: number): void'''

'''anchor_id''': ID of the html element to place the animated score onto (without the '#')

'''color''': hexadecimal RGB representation of the color (should be the color of the scoring player), but without a leading '#'. For instance, 'ff0000' for red.

'''score''': numeric score to display, prefixed by a '+' or '-'

'''duration''': animation duration in milliseconds (optional, default is 1000)

'''offset_x''' and '''offset_y''': if both offset_x and offset_y are defined and not null, apply the following offset (in pixels) to the scoring animation.
Note that the score is centered in the anchor, so the offsets might have to be negative if you calculate the position.

Note: if you want to display successively each score, you can use ''this.notifqueue.setSynchronous()'' function.
<pre>
setupNotifications: function() {
dojo.subscribe( 'displayScoring', this, "notif_displayScoring" );
...
}
...

notif_displayScoring: function(notif) {
const duration = notif.args.duration?notif.args.duration:1000;
this.notifqueue.setSynchronous('displayScoring', duration );
this.displayScoring( notif.args.target, notif.args.color, notif.args.score, duration);
},
</pre>

=== Speech bubble ===

For better interactivity in some games (Love Letter for example), you may use comic book style speech bubbles to express the players voices.
This is done with showBubble:

'''this.showBubble(anchor_id: string, text: string, delay?: number, duration?: number, custom_class?: string): void'''

* anchor_id - where to attach the bubble
* text - what to put in bubble, can be html
* delay - delay in milliseconds (optional, default 0)
* duration - duration of animation in milliseconds (optional, default 3000)
* custom_class - extra class to add to bubble (optional), if you need to override the default bubble style

<pre>
this.showBubble('meeple_2', _('Hello'), 0, 1000, 'pink_bubble');
</pre>

<pre>
notif_speechBubble(notif) {
var html = this.format_string_recursive(notif.args.text, notif.args.args);
this.showBubble(notif.args.target, html, notif.args.delay ?? 0, notif.args.duration ?? 1000);
},
</pre>

'''Warning''': if your bubble could overlap other active elements of the interface (buttons in particular), as it stays in place even after disappearing, you should use a custom class to give it the style "pointer-events: none;" in order to intercept click events.

Note: If you want this visually, but want to take complete control over this bubble and its animation (for example to make it permanent) you can just use div with 'discussion_bubble' class on it, and content of div is what will be shown.

== Translations ==

See [[Translations]]

== Players panels ==

=== Update players score ===

The column player_score from the player table is automatically loaded into this.scoreCtrl and therefore into the stars location on the player board. This occurs sometime after the game setup() function. However this score must be updated as the game progresses using notifications.

Note: this.scoreCtrl[player_id] is object of class [[Counter]], you can use other counter API.

Increase a player score (with a positive or negative number):

<pre>
this.scoreCtrl[ player_id ].incValue( score_delta );
</pre>

Set a player score to a specific value:

<pre>
this.scoreCtrl[ player_id ].setValue( new_score );
</pre>

Set a player score to a specific value with animation:

<pre>
this.scoreCtrl[ player_id ].toValue( new_score );
</pre>

Typical usage would be (that will process 'score' notification):
<pre>
setupNotifications : function() {
...
dojo.subscribe('score', this, "notif_score");
},
notif_score: function(notif) {
this.scoreCtrl[notif.args.player_id].setValue(notif.args.player_score);
},
</pre>

=== Adding stuff to player's panel ===

At first, create a new "JS template" string in your template (tpl) file:

(from Gomoku example)
<pre>
var jstpl_player_board = '\<div class="cp_board">\
<div id="stoneicon_p${id}" class="gmk_stoneicon gmk_stoneicon_${color}"></div><span id="stonecount_p${id}">0</span>\
</div>';
</pre>

Then, you add this piece of code in your JS file to add this template to each player panel:

<pre>
// Setting up player boards
for( var player_id in gamedatas.players )
{
var player = gamedatas.players[player_id];

// Setting up players boards if needed
var player_board_div = $('player_board_'+player_id);
dojo.place( this.format_block('jstpl_player_board', player ), player_board_div );
}
</pre>

(Note: the code above is of course from your "setup" function in your Javascript).

Very often, you have to distinguish current player and others players. In this case, you just have to create another JS template (ex: jstpl_otherplayer_board) and use it when "player_id" is different than "this.player_id".

=== Fixing Player Panel heights ===

You may find that the player panels don't automatically resize when adding something to (or removing something from) a player panel while the display is in portrait mode (i.e. the player summary panels are at the top of the screen rather than down the right side).

When this happens, call <pre>this.adaptPlayersPanels();</pre> This recalculates the layout and also adjusts the position of the actionbar for you.

=== Player's panel disabling/enabling ===

'''this.disablePlayerPanel(player_id: number): void'''

Disable given player panel (the panel background become gray).

Usually, this is used to signal that this played passes, or will be inactive during a while.

Note that the only effect of this is visual. There are no consequences on the behaviour of the panel itself.

'''this.enablePlayerPanel(player_id:number): void'''

Enable a player panel that has been disabled before.

'''this.enableAllPlayerPanels(): void'''

Enable all player panels that has been disabled before.

=== Player order ===

'''this.updatePlayerOrdering(): void'''

This function makes sure that player order in player's panel matches this.gamedatas.playerorder and its normally called by framework.
You can call it yoursel if you change this.gamedatas.playerorder from notification.
Also you can override this function to change defaults OR insert a non-player panel [[BGA_Studio_Cookbook#Inserting_non-player_panel]].

=== Counters ===
Note: there is a bga component called "ebg/counter", this API is not using it. These methods below are declared right in the core game. If you need animation for counters use ebg/counter

To use this API just create a counter dom element like this (class does not really matter)
<pre>
<div class="counter" id="bread"></div>
<div class="counter" id="coin"></div>
</pre>
The "bread" div will be the counter name.

The php code should send all "counters" data from getAllDatas() method like this

game.php
<pre>
protected function getAllDatas() {
// (the key must match counter_name)
$result['counters']=[
'bread' => [
'counter_name' => 'bread',
'counter_value' => 3
],
'coin' => [
'counter_name' => 'coin',
'counter_value' => 5
]
];
return $result;
}
</pre>

'''setCounter(counter_name: stirng, new_value: string | number): void'''

updates the global this.gamedatas.counters and value of node $(counter_name)
<pre>
notif_counter: function(notif) {
this.setCounter(notif.args.counter_name, notif.args.counter_value);
},
</pre>

'''incCounter(counter_name: string, delta: number): void'''
<pre>
notif_counter : function(notif) {
this.incCounter(notif.args.counter_name, notif.args.inc);
},
</pre>

'''updateCounters(counters: object): void'''

Useful for updating game counters in the player panel (such as resources).
'counters' arg is map of counters (the key must match counter_name)
{
'bread': {
'counter_name' : 'bread',
'counter_value' => 3
},
'coin': {
'counter_name' : 'coin',
'counter_value' => 5
}
}
All counters MUST be referenced in this.gamedatas.counters (means they should be send from php) and will be updated.
DOM objects referenced by 'counter_name' will have their innerHTML updated with 'counter_value'.

Usually you call this from notification

<pre>
notif_counter : function(notif) {
this.updateCounters(notif.args.counters);
},
</pre>

== BGA GUI components ==

BGA framework provides some useful ready-to-use components for the game interface:

[[Studio#BGA_Studio_game_components_reference]]

Note that each time you are using an additional component, you must declare it at the top of your Javascript file in the list of modules used.

Example if you are using "ebg.stock":
<pre>
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/stock" /// <=== we are using ebg.stock module
],
</pre>

== BGA Buttons ==

=== Basic Button ===

'''this.addActionButton(id: string, label: string, method: string | eventhandler, destination?: string, blinking?: boolean, color?: string): void'''

You can use this method to add an action button in the main action status bar (or other places).

Arguments:
* id: an element ID that should be unique in your HTML DOM document.
* label: the text of the button. Should be translatable (use _() function). Note: this can also be any html, such as "<div class='brick'></div>", see example below on how to make image action buttons.
* method: the name of your method that must be triggered when the player clicks on this button (can be name of the method on game class or handler).
* destination (optional): id of parent on where to add button, ONLY use in rare cases if location is not action bar. Use '''null''' as value if you need to specify other arguments.
* blinking (optional): if set to '''true''', the button is going blink to catch player's attention. Please DO NOT abuse blinking button. If you need button to blink after some time passed add class 'blinking' to the button later.
* color: could be '''blue''' (default), '''red''','''gray''' or '''none'''.

You should only use this method in your "onUpdateActionButtons" method. Usually, you use it like this:

<pre>
onUpdateActionButtons: function( stateName, args ) {
if (this.isCurrentPlayerActive()) {
switch( stateName ) {
case 'giveCards':
this.addActionButton( 'giveCards_button', _('Give selected cards'), 'onGiveCards' );
this.addActionButton( 'pass_button', _('Pass'), () => this.bgaPerformAction('actPass') );
break;
}
}
},
</pre>

In the example above, we are adding a "Give selected cards" button in the case we are on game state "giveCards". When player clicks on this button, it triggers our "onGiveCards" method.

Example using blinking red button:
<pre>
this.addActionButton( 'button_confirm', _('Confirm?'), 'onConfirm', null, true, 'red');
</pre>

If you want to call the handler with arguments, you can use arrow functions, like this:
<pre>
this.addActionButton( 'commit_button', _('Confirm'), () => this.onConfirm(this.selectedCardId), null, false, 'red');
</pre>

=== Image Button ===

You can use the same method, but add extra class to a button to disable the padding and style it, i.e.
<pre>
this.addActionButton( 'button_brick', '<div class="brick"></div>', ()=>{... on brick ...}, null, null, 'gray');
dojo.addClass('button_brick','bgaimagebutton');
</pre>

where

<pre>
.bgaimagebutton {
padding: 0px 12px;
min-height: 28px;
border: none;
}
</pre>

If you use this a lot, you can define a helper function, i.e.
<pre>
/**
* This method can be used instead of addActionButton, to add a button which is an image (i.e. resource). Can be useful when player
* need to make a choice of resources or tokens.
*/
addImageActionButton: function(id, div, handler, bcolor, tooltip) {
if (typeof bcolor == "undefined") {
bcolor = "gray";
}
// this will actually make a transparent button id color = gray
this.addActionButton(id, div, handler, null, false, bcolor);
// remove border, for images it better without
dojo.style(id, "border", "none");
// but add shadow style (box-shadow, see css)
dojo.addClass(id, "shadow bgaimagebutton");
// you can also add additional styles, such as background
if (tooltip) {
dojo.attr(id, "title", tooltip);
}
return $(id);
},
</pre>

=== Disabling Button ===

You can disable the '''bgabutton''' by adding the css class '''disabled''' in you js. The disabled button is still visible but is grey and not clickable.
For example in the '''onUpdateActionButtons''' :
<pre>
this.addActionButton('play_button_id', _('Play 1 to 3 cards'), 'playFunctionButton');
if (condition) {
dojo.addClass('play_button_id', 'disabled');
}
</pre>

=== Custom Buttons ===

You can create a custom button, but the BGA framework provides a standard button that requires only .css classes: '''bgabutton''' and '''bgabutton_${color}'''.

'''Examples:'''

<pre>
<a href="#" id="my_button_id" class="bgabutton bgabutton_blue"><span>My blue button</span></a>

<a href="#" id="my_button_id" class="bgabutton bgabutton_red bgabutton_big"><span>My big red button</span></a>
</pre>

'''Note''': To see it in action, check out ''Coloretto''.

=== Button outside of action bar ===

Use addActionButton() method with destination argument set
<pre>
this.addActionButton( 'commit_button', _('Confirm'), 'onConfirm', 'player_board', true, 'red');
</pre>

in example above the button will be place on object with id 'player_board'

== Image loading ==

See also [[Game_art:_img_directory]].

'''Be careful''': by default, ALL images of your img directory are loaded on a player's browser when he loads the game. For this reason, don't let in your img directory images that are not useful, otherwise it's going to slowdown the game load.

'''this.dontPreloadImage(image_file_name: string)'''

Using dontPreloadImage, you tell the interface to not preload a specific image in your img directory.

Example of use:
<pre>
this.dontPreloadImage( 'cards.png' );
</pre>

This is particularly useful if for example you have 2 different themes for a game. To accelerate the loading of the game, you can specify to not preload images corresponding to the other theme.

Another example of use: in "Gosu" game with Kamakor extension, you play with 5 sets of cards among 10 available. Cards images are organized by sets, and we only preload the images corresponding to the 5 current sets with '''ensureSpecificGameImageLoading( image_file_names_array )'''.
<pre>
// By default, do not preload anything
this.dontPreloadImage( 'cards.png' );
this.dontPreloadImage( 'clan1.png' );
this.dontPreloadImage( 'clan2.png' );
this.dontPreloadImage( 'clan3.png' );
this.dontPreloadImage( 'clan4.png' );
this.dontPreloadImage( 'clan5.png' );
this.dontPreloadImage( 'clan6.png' );
this.dontPreloadImage( 'clan7.png' );
this.dontPreloadImage( 'clan8.png' );
this.dontPreloadImage( 'clan9.png' );
this.dontPreloadImage( 'clan10.png' );
var to_preload = [];
for( i in this.gamedatas.clans )
{
var clan_id = this.gamedatas.clans[i];
to_preload.push( 'clan'+clan_id+'.png' );
}

this.ensureSpecificGameImageLoading( to_preload );

</pre>

'''Note:''' You don't need to specify to not preload game box images (game_box.png, game_box75.png...) since they are not preloaded by default.

'''this.ensureSpecificGameImageLoading(list: string[])'''

This is oppostive of dontPreloadImage - its ensure specific images is loaded. Note: only makes sense if preload list is empty, otherwise everything is loaded anyway

'''load specific images'''
All images that will be preloaded stored in g_img_preload. If you want to override it directly - there is no API, but you can do this in GAME constructor

g_img_preload = ['tokens.png', 'trains.png', 'loc_plan.png', 'eng.png', 'eng-back.png'];

You can also set it to empty array and call ensureSpecificGameImageLoading() on specific images

== Sounds ==

Add a custom sound and make it load with your interface:

Add this in your template (.tpl) file:
<pre>
<audio id="audiosrc_<gamename>_<yoursoundname>" src="{GAMETHEMEURL}img/<gamename>_<yoursoundname>.mp3" preload="none" autobuffer></audio>
<audio id="audiosrc_o_<gamename>_<yoursoundname>" src="{GAMETHEMEURL}img/<gamename>_<yoursoundname>.ogg" preload="none" autobuffer></audio>
</pre>

Note: this is a requirement to provide both a mp3 and a ogg file with the names <code><gamename>_<yoursoundname>[.ogg][.mp3]</code>.

Play the sound (from your .js file):

<pre>
playSound('<gamename>_<yoursoundname>'); // do not add 'this.' - its a global function
</pre>

Disable the standard "move" sound for this move (to replace it with your custom sound):

Add this to your notification handler:

<pre>
this.disableNextMoveSound();
</pre>

Note: it only disable the sound for the next move.

== Title bar and states ==

=== Client states ===

Client states is a way to simulate the state transition but without actually going
to server. It is usefull when you need to ask user multiple questions before you
send things to server

'''this.setClientState(newState: string, args: object)'''

Example:
this.setClientState("client_playerPicksLocation", {
descriptionmyturn : _("${you} must select location"),
});

For more information see [[BGA_Studio_Cookbook#Multi_Step_Interactions:_Select_Worker.2FPlace_Worker_-_Using_Client_States]]

'''this.restoreServerGameState()'''
If you are in client state it will restore the current server state (cheap undo)

'''this.on_client_state'''
Boolean indicating that we are in client state

=== Title bar ===
If you simply want to show something in title bar you can do it directly
$('pagemaintitletext').innerHTML = text;

This however will not work with parameters and will not draw You in color,
if you want to do proper args rendering use method below

;'''this.removeActionButtons()'''
Removes all buttons from title bar

;'''this.updatePageTitle()'''
:This function allows to update the current page title and turn description according to the game state arguments. If the current game state description this.gamedatas.gamestate.descriptionmyturn is modified before calling this function it allows to update the turn description without changing state. This will handle arguments substitutions properly.

Note: this functional also will calls this.onUpdateActionButtons, if you want different buttons then state defaults, use method in example to replace them, if it becomes too clumsy use client states (see above)

Example from Terra Mystica:
<pre>
onClickFavorTile: function( evt ) {
...
if ( ... ) {
this.gamedatas.gamestate.descriptionmyturn = _('Special action: ') + _('Advance 1 space on a Cult track');
this.updatePageTitle();
this.removeActionButtons();
this.addActionButton( ... );
...
return;
}
...

}
</pre>

== User preferences ==
'''this.getGameUserPreference(pref_id)'''

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

'''this.setGameUserPreference(pref_id, value)'''

Programmatically change a user preference. It will have the same effect as if the player changed the value in the select combo box, in the top-right menu.

'''this.onGameUserPreferenceChanged'''

A callback you can define if you want to be notified when a user changes a user preference.

Example:<pre>
onGameUserPreferenceChanged: function(pref_id, pref_value) {
switch (pref_id) {
case 201:
document.getElementsByTagName('html')[0].classList.toggle('dark-background', pref_value == 2);
break;
}
}
</pre>

== Other useful stuff ==

'''dojo.hitch'''

With dojo.hitch, you can create a callback function that will run with your game object context whatever happen.

Typical example: display a BGA confirmation dialog with a callback function created with dojo.hitch:

<pre>
this.confirmationDialog( _('Are you sure you want to make this?'), dojo.hitch( this, function() {
this.bgaPerformAction('makeThis');
} ) );
</pre>

In the example above, using dojo.hitch, we ensure that the "this" object will be set when the callback is called.

NOTE: In modern JS there are lambdas that eliminate need for that, the example above will look like this
<pre>
this.confirmationDialog( _('Are you sure you want to make this?'), () => this.bgaPerformAction( 'makeThis') );
</pre>

;'''onScreenWidthChange()'''
:This function can be overridden in your game to manage some resizing on the client side when the browser window is resized. This function is also triggered at load time, so it can be used to adapt to the :viewport size at the start of the game too.

; this.bRealtime
: Return true if the game is in realtime. Note that having a distinct behavior in realtime and turn-based should be exceptional.

; g_replayFrom
: Global contains replay number in live game, it is set to undefined (i.e. not set) when it is not a replay mode, so consequentially the good check is '''typeof g_replayFrom != 'undefined'''' which returns true if the game is in replay mode <i>during the game</i> (the game is ongoing but the user clicked "replay from this move" in the log)

; g_archive_mode
: Returns true if the game is in archive mode <i>after the game</i> (the game has ended)

; this.instantaneousMode
: Returns true during replay/archive mode if animations should be skipped. Only needed if you are doing custom animations. (The BGA-provided animation functions like <i>this.slideToObject()</i> automatically handle instantaneous mode.)
: Technically, when you click "replay from move #20", the system replays the game from the very beginning with moves 0 - 19 happening in instantaneous mode and moves 20+ happening in normal mode.

; g_tutorialwritten
: Returns an object like the below if the game is in tutorial mode, or undefined otherwise. Tutorial mode is a special case of archive mode where comments have been added to a previous game to teach new players the rules.
{
author: "91577332",
id: "576",
mode: "view"
status: "alpha"
version_override: null
viewer_id: "84554161"
}

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

[[Category:Studio]]

Game interface logic: Game.js

2024-09-25T18:26:43Z

Sguzzer Gunayer: /* Counters */

{{Studio_Framework_Navigation}}

__TOC__

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

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

== File structure ==

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

Here is the basic structure:

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

More details:

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

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

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

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

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

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

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

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

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

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

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

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

== Dojo framework ==

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

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

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

== Javascript minimization (after July 2020) ==

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

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

== Accessing Players Information ==

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

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

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

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

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

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

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

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

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

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

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

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

== Accessing and manipulating the DOM ==

=== Element by Id ===

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

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

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

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

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

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

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

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

=== Style ===

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

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

Examples:

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

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

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

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

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

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

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

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

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

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

=== Classes ===

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

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

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

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

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

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

Example from ''Reversi'':

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

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

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

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

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

'''Vanilla JS classList'''

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

=== Attributes ===

;dojo.attr

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

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

'''Vanilla JS attr'''

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

=== Queries ===

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

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

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

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

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

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

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

'''Vanilla JS query'''

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

=== Creating and Destroying elements ===

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

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

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

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

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

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

Create element

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

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

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

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

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

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

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

const div = ``;
'''this.format_string_recursive'''

This bga function is similar to this.format_string but is capable of processing recursive argument structures and translations. It is used to format server notifications.

TODO: find better place for these function docs

=== Moving elements ===

'''dojo.place(node: string | Element, refNode: ElementOrId, pos?: string | number): Element'''

dojo.place is the best function to insert HTML code somewhere in your game interface without breaking something. It is much better to use than the '''innerHTML=''' method if you must insert HTML tags and not only values.

node: can be a string or a DOM node. If it is a string starting with “<”, it is assumed to be an HTML fragment, which will be created. Otherwise it is assumed to be an id of a DOM node.

<pre>
// Insert your HTML code as a child of a container element
dojo.place( "<div class='foo'></div>", "your_container_element_id" );
</pre>

pos: optional argument. Can be a number or one of the following strings: “before”, “after”, “replace”, “only”, “first”, or “last”. If omitted, “last” is assumed.

* "replace": replace the container element with my_node element
* "first": places the node as a child of the reference node. The node is placed as the first child.
* "last" (default): places the node as a child of the reference node. The node is placed as the last child.
* "before": places the node right before the reference node.
* "after": places the node right after the reference node.
* "only": replaces all children of the reference node with the node.

this parameter can be a positive integer. In this case, the node will be placed as a child of the reference node with this number (counting from 0). If the number is more than number of children, the node will be appended to the reference node making it the last child.

<pre>
// Replace all children of container with my_node
dojo.place( $('my_node'), "your_container_element_id", "only" );
</pre>

See also full doc on dojo.place: [https://dojotoolkit.org/reference-guide/1.7/dojo/place.html]

Usually, when you want to insert some piece of HTML in your game interface, you should use "[[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl#Javascript_templates|Javascript templates]]".

But you can also relocate elements like that. Note: it won't animate if you do that.

'''this.placeOnObject(mobile_obj: ElementOrId, target_obj: ElementOrId): void'''

places mobile_obj on target_obj, set the absolute positions and centers the mobile_obj on target_obj,
effect is immediate

This is not really an animation, but placeOnObject is frequently used before starting an animation.

Example:
<pre>
// (We just created an object "my_new_token")

// Place the new token on current player board
this.placeOnObject( "my_new_token", "overall_player_board_"+this.player_id );

// Then slide it to its position on the board
this.slideToObject( "my_new_token", "a_place_on_board" ).play();
</pre>

'''this.placeOnObjectPos(mobile_obj: ElementOrId, target_obj: ElementOrId, target_x: number, target_y: number): void'''

This method works exactly like placeOnObject, except than you can specify some (x,y) coordinates (in px). This way, the center of "mobile_obj" will be placed to the specified x,y position relatively to the center of "target_obj".

''Note: the placement works differently from this.slideToObjectPos'', since coordinates are calculated based on the center of objects.

'''this.attachToNewParent(mobile_obj: ElementOrId, target_obj: ElementOrId): void'''

With this method, you change the HTML parent of "mobile_obj" element without moving it.
"target_obj" is the new parent of this element. The beauty of
attachToNewParent is that the mobile_obj element DOES NOT MOVE during this process.

What happens is that the method calculate a relative position of mobile_obj to make sure it does not move after the HTML parent changes.

Why using this method?

Changing the HTML parent of an element can be useful for the following reasons:
* When the HTML parent moves, all its child are moving with them. If some game elements is no more linked with a parent HTML object, you may want to attach it to another place.
* The z_order (vertical order of display) depends on the position in the DOM, so you may need to change the parent of some game elements when they are moving in your game area.

'''CAREFUL''': this function destroys original object and places a clone onto a new parent, this will break all references to this HTML element (ex: dojo.connect).
If you need version that does not destroy the object but the same otherwise see [[BGA_Studio_Cookbook#Attach_to_new_parent_without_destroying_the_object]]

== Animations ==

===Dojo Animations===

BGA animations is based on Dojo Animation ([http://dojotoolkit.org/documentation/tutorials/1.8/animation/ see tutorial here]).

However, most of the time, you can just use methods below, which are built on top of Dojo Animation.

Note: one interesting method from Dojo that could be useful from time to time is "Dojo.Animation". It allows you to make any CSS property "slide" from one value to another.

Note 2: the slideTo methods are not compatible with CSS transform (scale, zoom, rotate...). If possible, avoid using CSS transform on nodes that are being slided. Eventually, the only possible solution to make these 2 compatible is to disable all CSS transform properties, use slideToObjectPos/placeOnObjectPos, and then apply them again.

===Sliding===

'''this.slideToObject(mobile_obj: ElementOrId, target_obj: ElementOrId, duration?: number, delay?: number): Animation'''

You can use slideToObject to "slide" an element to a target position.

Sliding element on the game area is the recommended and the most used way to animate your game interface. Using slides allow players to figure out what is happening on the game, as if they were playing with the real boardgame.

The parameters are:
* mobile_obj: the ID of the object to move. This object must be "relative" or "absolute" positioned.
* target_obj: the ID of the target object. This object must be "relative" or "absolute" positioned. Note that it is not mandatory that mobile_obj and target_obj have the same size. If their size are different, the system slides the center of mobile_obj to the center of target_obj.
* duration: (optional) defines the duration in millisecond of the slide. The default is 500 milliseconds.
* delay: (optional). If you defines a delay, the slide will start only after this delay. This is particularly useful when you want to slide several object from the same position to the same position: you can give a 0ms delay to the first object, a 100ms delay to the second one, a 200ms delay to the third one, ... this way they won't be superposed during the slide.

BE CAREFUL: The method returns an dojo.fx animation, so you can combine it with other animation if you want to. It means that you have to call the "play()" method, otherwise the animation WON'T START.

Example:
<pre>
this.slideToObject( "some_token", "some_place_on_board" ).play();
</pre>

'''this.slideToObjectPos(mobile_obj: ElementOrId, target_obj: ElementOrId, target_x: number, target_y: number, duration?: number, delay?: number): Animation'''

This method does exactly the same as "slideToObject", except than you can specify some (x,y) coordinates. This way, "mobile_obj" will slide to the specified x,y position relatively to "target_obj".

Example: slide a token to some place on the board, 10 pixels from the top:
<pre>
this.slideToObjectPos( "some_token", "some_place_on_board", 0, 10 ).play();
</pre>

'''this.slideTemporaryObject(mobile_obj_html: string, parent: ElementOrId, from: ElementOrId, to: ElementOrId, duration?: number, delay?: number): Animation'''

This method is useful when you want to slide a temporary HTML object from one place to another. As this object does not exists before the animation and won't remain after, it could be complex to create this object (with dojo.place), to place it at its origin (with placeOnObject) to slide it (with slideToObject) and to make it disappear at the end.

slideTemporaryObject does all of this for you:
* mobile_obj_html is a piece of HTML code that represent the object to slide.
* parent is the ID of an HTML element of your interface that will be the parent of this temporary HTML object.
* from is the ID of the origin of the slide.
* to is the ID of the target of the slide.
* duration/delay works exactly like in "slideToObject"

Example:
<pre>
this.slideTemporaryObject( '<div class="token_icon"></div>', 'tokens', 'my_origin_div', 'my_target_div' ).play();
</pre>

===Destroy===
'''this.slideToObjectAndDestroy(mobile_obj: ElementOrId, target_obj: ElementOrId, duration?: number, delay?: number): void'''

This method is a handy shortcut to slide an existing HTML object to some place then destroy it upon arrival. It can be used for example to move a victory token or a card from the board to the player panel to show that the player earns it, then destroy it when we don't need to keep it visible on the player panel.

It works the same as this.slideToObject and takes the same arguments, but it starts the animation.

CAREFUL: Make sure nothing is creating the same object at the same time the animation is running, because this will cause some random disappearing effects

Example:
<pre>
this.slideToObjectAndDestroy( "some_token", "some_place_on_board", 1000, 0 );
</pre>

'''this.fadeOutAndDestroy( node: string | Element, duration?: number, delay?: number):''' '''void'''

This function fade out the target node, then destroy it. Its starts the animation.
* duration/delay works exactly like in "slideToObject"

Example:
<pre>
this.fadeOutAndDestroy( "a_card_that_must_disappear" );
</pre>

CAREFUL: the HTML node still exists until during few milliseconds, until the fadeOut has been completed.
Make sure nothing is creating same object at the same time as animation is running, because you will be some random dissapearing effects

===Rotating elements===

This example combines "Dojo.Animation" method and a CSS property transform that allow you to rotate the element.
<pre>
// node is Element we rotating
var animation = new dojo.Animation({
curve: [fromDegree, toDegree],
onAnimate: (v) => {
node.style.transform = 'rotate(' + v + 'deg)';
}
});

animation.play();
</pre>

BGA has its own interface to rotate

'''this.rotateTo(node: string | Element, degree: number): void'''

It starts the animation, and stored the rotation degree in the class, so next time you rotate object - it is additive.
There is no animation hooks in this one, if you need to change any parameters use dojo animation above.

There is also '''rotateInstantTo''' with same signature which does not animate

===Animation Callbacks===

If you wish to run some code only after an animation has completed you can do this by linking a callback method to 'onEnd'.

<pre>
var animation_id = this.slideToObject( mobile_obj, target_obj, 500 );
dojo.connect(animation_id, 'onEnd', () => {
// do something here
});
animation_id.play();
</pre>

If you wish to call a second animation after the first (rather than general code) then you can use a dojo animation chain (see tutorial referenced above).

== Players input ==

=== Connecting ===
'''dojo.connect(element: Element, event: string, context: object, method: eventHandler): any'''

'''dojo.connect(element: Element, event: string, handler: eventHandler): any'''

Used to associate a player event with one of your notification methods.

Example: associate a click on an element ("my_element") with one of our methods ("onClickOnMyElement"):
<pre>
dojo.connect( $('my_element'), 'onclick', this, 'onClickOnMyElement' );
</pre>

Same idea but based on query (i.e. all element of 'pet' class)
dojo.query(".pet").connect('onclick', this, 'onPet');

Note: if you need to disconnect the handler you have to store handler returned from this method, i.e.

<pre>
var handler = dojo.connect(...);
...
dojo.disconnect(handler);
</pre>

If you don't store the handler - you have to destroy the object to disconnect it

Typical function that implements the input handler will look like this

<pre>
onPet: function(event) {
var id = event.currentTarget.id;
console.log('onPet ' + id);
dojo.stopEvent(event);
if (this.gamedatas.gamestate.name == 'playerTurnPet') {
this.bgaPerformAction('actPlayPet', {card: id});
} else {
this.showMoveUnauthorized();
}
}
</pre>

'''this.connect(element: ElementOrId, event: string, method: eventHandler): void'''

Used to associate a player event with one of your notification methods.

this.connect( $('my_element'), 'onclick', 'onClickOnMyElement' );

Or you can use an in-place handler

this.connect( $('my_element'), 'onclick', (e) => { console.log('boo'); } );

Note that this function stores the connection handler. That is the only real difference between '''this.connect''' and '''dojo.connect'''. If you plan to destroy the element you connected, you '''must''' call this.disconnect() to prevent memory leaks.
This function is mainly for permanent objects - if you just want to connect the temp object you should probably not use this method but use dojo.connect which won't require any clean-up.

'''this.connectClass(cssClassName: string, event: string, method: eventHandler): void'''

Same as connect(), but for all the nodes set with the specified cssClassName.
this.connectClass('pet', 'onclick', 'onPet');
'''this.disconnect(element: ElementOrId, event: string): void'''

Disconnect event handler (previously registered with this.connect or this.connectClass).

this.disconnect( $('my_element'), 'onclick');

Note: dynamic connect/disconnect is for advanced cases ONLY, you should always connect elements statically if possible, i.e. in setup() method.

'''this.disconnectAll(): void'''

Disconnect all previously registed event handlers (registered via this.connect or this.connectClass)

this.disconnectAll();

=== Actions ===

'''this.bgaPerformAction(action: string, args?: object, options: object = { lock: true, checkAction: true }): Promise<void>'''

Triggers an action on the backend. This is a combination of checkAction and ajaxcall, returning a Promise which resoves when ajaxcall ends.

This method must be used to send a player input to the game server. '''It should not be triggered programmatically''', especially not in loops, in callbacks, in notifications, or in onEnteringState/onUpdateActionButtons/onLeavingState, in order not to create race conditions or break replay game and tutorial features. It should be used only in reaction to a user action in the interface.

* action: name of the action, as it is written in "possibleactions" of the current state.
* args: an object containing the call parameters to send to the action
* options: options to tweak the call with some defaults. Default is <code>{ lock: true, checkAction: true }</code>.

Example of a standard call without args:
this.bgaPerformAction('pass');

Example of a standard call with action args:
this.bgaPerformAction('actPlayCard', { id: this.selectedCardId });

Example of a call without checking action (because player is inactive in a multiactive state):

this.bgaPerformAction('actChangeMind', {}, { checkAction: false });

Example of a call without lock (because of a special action not directly related to the game flow):

this.bgaPerformAction('actSetAutoBid', { alwaysBidUntil: 500 }, { lock: false, checkAction: false });

Example of call with reaction to exception:
this.bgaPerformAction('actPlayCard', { id: this.selectedCardId }).catch(()=>{ this.selectedCardId = undefined; });

Example of call with reaction to success:
this.bgaPerformAction('actPlayCard', { id: this.selectedCardId }).then(()=>{ this.unselectAll(); });

'''this.ajaxcall(url, parameters, obj_callback, callback, callback_anycase?, ajax_method?: string)'''

''Note: bgaPerformAction is a simpler way to use ajax calls, ajaxcall stays in the doc for legacy reasons only and should not be used in new projects.''

Same warning as '''this.bgaPerformAction''' about using on user action only.

* url: the url of the action to perform. For a game, it must be: "/<mygame>/<mygame>/myAction.html"
* parameters: an array of parameter to send to the game server.
** Note that "lock: true" must always be specified in this list of parameters in order the interface can be locked during the server call. Cannot use lock: false - to not lock it has to be undefined.
** Note: Restricted parameter names (please don't use them):
*** "action"
*** "module"
*** "class"
* obj_callback: must be set to "this".
* callback (non-optional but rarely used): a function to trigger when the server returns result and everything went fine (not used, as all data handling is done via notifications).
* callback_anycase: (optional) a function to trigger when the server returns ok OR error. If no error this function is called with parameter value false. If an error occurred, the first parameter will be set to true, the second will contain the error message sent by the PHP back-end, and the third will contain an error code.
* ajax_method: (optional and rarely used) if you need to send large amounts of data (over 2048 bytes), you can set this parameter to 'post' (all lower-case) to send a POST request as opposed to the default GET. This works, but was not officially documented, so only use if you really need to.

Usage:
<pre>
this.ajaxcall( '/mygame/mygame/actMyAction.html', { lock: true,
arg1: myarg1,
arg2: myarg2
}, this, (result)=>{} );
</pre>

'''this.checkAction(action: string, nomessage?: boolean): boolean '''

Check if player can do the specified action by taking into account:
* if interface is locked it will return false and show message "An action is already in progress", unless nomessage set to true
* if player is not active it will return false and show message "This is not your turn", unless nomessage set to true
* if action is not in list in possible actions (defined by "possibleaction" in current game state) it will return false and show "This move is not authorized now" error (unconditionally).
* otherwise returns true
Example:
<pre>
function onClickOnGameElement( evt ) {
if( this.checkAction( "actMyAction" ) ) {
// Do the action
}
}
</pre>

'''this.checkPossibleActions(action: string): boolean'''

* this is independent of the player being active, so can be used instead of this.checkAction(). This is particularly useful for multiplayer states when the player is not active in a 'player may like to change their mind' scenario. Unlike this.checkAction, this function does NOT take interface locking into account

* if action is not in list in possible actions (defined by "possibleaction" in current game state) it will return false and show "This move is not authorized now" error (unconditionally).
* otherwise returns true

function onChangeMyMind( evt ) {
if( this.checkPossibleActions( "actMyAction" ) ) {
// Do the action
}
}

'''this.checkLock(nomessage?: boolean): boolean'''

When using "lock: true" in ajax call you can use this function to check if interface is in lock state (it will be locked during server call and notification processing).
This check can be used to block some other interactions which do not result in ajaxcall or if you want to suppress errors. Note: normally you only need to use this.checkAction(...), this is for advanced cases.

It will also show error unless nomessage is set to true

function onChangeMyMind( evt ) {
if( this.checkLock() ) {
// Do the action
}
}

== Notifications ==

When something happens on the server side, your game interface Javascript logic received a notification.
If you have not done so yet check what notification are in [[Main_game_logic:_yourgamename.game.php#Notifications]]

Here's how you can handle these notifications on the client side.

=== Subscribe to notifications ===

'''dojo.subscribe(notif_type: string, callback_obj: Object, handler: string|handler)'''
* notif_type - notification type/name send by php server
* callback_obj - usually this
* handler - if string method of callback_obj with name name is called, when notification is called, with notification object as parameter (see below)

Your Javascript "setupNotifications" method is the place where you can subscribe to notifications from your PHP code.

Here's how you associate one of your Javascript method to a notification "playDisc" (from Reversi example):

<pre>
setupNotifications: function() {
...
dojo.subscribe('playDisc', this, "notif_playDisc");
},
</pre>

Note: the "playDisc" corresponds to the name of the notification you define it in your PHP code, in your "notifyAllPlayers" or "notifyPlayer" method.

Then, you have to define your "notif_playDisc" method:

<pre>
notif_playDisc: function(notif) {
// Remove current possible moves (makes the board more clear)
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );
this.addDiscOnBoard( notif.args.x, notif.args.y, notif.args.player_id );
},
</pre>

In a notification handler like our "notif_playDisc" method, you can access all notifications arguments with "notif.args".

Example:

PHP

<pre>
$this->notifyAllPlayers( "apples", clienttranslate('player takes ${count} apples'), [ "count" => 3 ] );
</pre>

JavaScript

<pre>
setupNotifications: function() {
dojo.subscribe( 'apples', this, 'notif_apples' );
},

notif_apples: function(notif) {
//You can access the "count" like this:
alert("count = " + notif.args.count);
}
</pre>

=== The notification Object received by client ===

When sending a notification on your PHP, the client side will receive an Object with the following attributes:

* type - type of the notification (as passed by php function)
* log - the log string passed from php notification
* args - This is the arguments that you passed on your notification method on php
* bIsTableMsg - is true when you use [[Main_game_logic:_yourgamename.game.php#NotifyAllPlayers|NotifyAllPlayers]] method (false otherwise)
* channelorig - information about table ID (formatted as : "/table/t[TABLE_NUMBER]")
* gamenameorig - name of the game
* move_id - ID of the move associated with the notification
* table_id - ID of the table (comes as string)
* time - UNIX GMT timestamp
* uid - unique identifier of the notification
* h - unknown

'' Note that those information were inferred from observation on console log. If an Admin can confirm/correct (and remove this line), you're welcome :)''

=== Ignoring notifications ===

Sometimes you need to ignore some notification on client side. You don't want them to be shown in game log and you don't want them to be handled.

The most common use case is when a player gets private information. They will receive a specific notification (such as "You received Ace of Heart"), while other players would receive more generic notification ("Player received a card").

In X.game.php
<pre>
$this->notifyAllPlayers("dealCard", clienttranslate('${player_name} received a card'), [
'player_id' => $playerId,
'player_name' => $this->getActivePlayerName()
]);

$this->notifyPlayer($playerId, "dealCardPrivate", clienttranslate('You received ${cardName}'), [
"type" => $card["type"],
"cardName" => $this->getCardName($card["type"])
]);
</pre>

The problem with this approach is that the active player will receive two notifications:
* Player1 received a card
* You received Ace of Hearts

Hence, notification ignoring.

NOTE: You can think that it would be possible to send such notification to all players except active just by using notifyPlayer and it seems to work. The problem however is that table spectators would miss such notification and their user interface (and game log) wouldn't be updated. Since there is no way to send notification just to spectators, ignoring the notification (or "filtering") is the only reasonable solution.

'''setIgnoreNotificationCheck(notif_type: string, predicate: ((notif: Notif)=>boolean))'''

This method will set a check whether any of notifications of specific type should be ignored.

The parameters are:
* notif_type: type of the notification
* predicate (notif => boolean): a function that will receive notif object and will return true if this specific notification should be ignored

Before dispatching any notification of this type, the framework will call predicate to check whether notification should be ignored, if it return true - the notification will be dispatched, i.e. logged or handled.

<pre>
this.notifqueue.setIgnoreNotificationCheck( 'dealCard', (notif) => (notif.args.player_id == this.player_id) );
</pre>

IMPORTANT: Remember that this notification is ignored on the client side, but was still received by the client. Therefore it shouldn't contain any private information as cheaters can get it. In other words this is not a way to hide information.

IMPORTANT: When a game is reloaded with F5 or when opening a turn based game, old notifications are replayed as history notification. They are used just to update the game log and are stripped of all arguments except player_id, i18n and any argument present in message. If you use and other argument in your predicate you should '''preserve''' it as explained [[Main_game_logic:_yourgamename.game.php#Notify_players|here]].

=== Synchronous notifications ===

When several notifications are received by your game interface, these notifications are processed immediately, one after the other, in the same exact order they have been generated in your PHP game logic.

However, sometimes, you need to give some time to the players to figure out what happened on the game before jumping to the next notification. Indeed, in many games, there are a lot of automatic actions, and the computer is going to resolve all these actions very fast if you don't tell it not to do so.

As an example, for Reversi, when someone is playing a disc, we want to wait 500 milliseconds before doing anything else in order the opponent player can figure out what move has been played.

Here's how we do this, right after our subscription:
<pre>
dojo.subscribe( 'playDisc', this, "notif_playDisc" );
this.notifqueue.setSynchronous( 'playDisc', 500 ); // Wait 500 milliseconds after executing the playDisc handler
</pre>

-----

It is also possible to control the delay timing dynamically (e.g., using notification args). As an example, maybe your notification 'cardPlayed' should pause for a different amount of time depending on the number or type of cards played.

For this case, use '''setSynchronous''' without specifying the duration and use '''setSynchronousDuration''' within the notification callback.

* NOTE: If you forget to invoke '''setSynchronousDuration''', the game will remain paused forever!

<pre>
setupNotifications: function () {
dojo.subscribe( 'cardPlayed', this, 'notif_cardPlayed' );
this.notifqueue.setSynchronous( 'cardPlayed' ); // wait time is dynamic
...
},

notif_cardPlayed: function (notif) {
// MUST call setSynchronousDuration

// Example 1: From notification args (PHP)
this.notifqueue.setSynchronousDuration(notif.args.duration);
...

// Or, example 2: Match the duration to a Dojo animation
var anim = dojo.fx.combine([
...
]);
anim.play();
this.notifqueue.setSynchronousDuration(anim.duration);
},
</pre>

You can also manually call this.notifqueue.setSynchronousDuration(0) once client operations are finished, but be careful that even fast replay still has a path to call it.

'''WARNING: combining synchronous and ignored notifications'''
You must be careful when combining dynamic synchronous durations (as described above) with ignored notifications. If you have a conditionally ignored notification like this (see below section):

<pre>this.notifqueue.setIgnoreNotificationCheck( 'myNotif', (notif) => (notif.args.player_id == this.player_id) /* or any other condition */ )</pre>

then you CANNOT do

<pre>this.notifqueue.setSynchronous('myNotif');</pre>

as, when the ignored check passes, the notification handler, in which `this.notifqueue.setSychronousDuration` is called, is never called and so the duration is never set and interface locking results.

The workaround is to set a "dummy" time:

<pre>this.notifqueue.setSynchronous('myNotif', 5000);</pre>

whose value is irrelevant but must be large enough to cover the time before the notification handler is called. The large value never actually comes into play because the notification is either ignored, or the synchronous duration is reset to a sensible value inside the handler.

=== Pre-defined notification types ===

'''tableWindow''' - This defines notification to display [[Game_interface_logic:_yourgamename.js#Scoring_dialogs|Scoring Dialogs]], see below.

'''message''' - This defines notification that shows on players log and have no other effect (technically any unhandled notification will do the same but its recommended to use this keyword for consistency)

// You can call this on php side without doing anything on client side
self::notifyAllPlayers( 'message', clienttranslate('hello'), [] );

'''simplePause''' - This notification will just delay other notifications, maybe useful if you know you need some extra time for animation or something. Requires a time parameter.

<pre>
self::notifyAllPlayers( 'simplePause', '', [ 'time' => 500] ); // time is in milliseconds
</pre>

Note: the following types are RESERVED by framework, do not use:

gameStateChange gameStateChangePrivateArg gameStateMultipleActiveUpdate newActivePlayer playerstatus yourturnack clockalert tableInfosChanged playerEliminated tableDecision archivewaitingdelay end_archivewaitingdelay replaywaitingdelay end_replaywaitingdelay replayinitialwaitingdelay end_replayinitialwaitingdelay aiPlayerWaitingDelay replay_has_ended updateSpectatorList wouldlikethink updateReflexionTime undoRestorePoint resetInterfaceWithAllDatas zombieModeFail zombieModeFailWarning aiError skipTurnOfPlayer zombieBack allPlayersAreZombie gameResultNeutralized playerConcedeGame showTutorial showCursor showCursorClick skipTurnOfPlayerWarning banFromTable resultsAvailable switchToTurnbased newPrivateState infomsg

== Tooltips ==

=== Adding static tooltips ===

'''this.addTooltip(nodeId: string, helpStringTranslated: string, actionStringTranslated: string, delay?: number): void'''

Add a simple text tooltip to the DOM node.

Specify 'helpStringTranslated' to display some information about "what is this game element?".
Specify 'actionStringTranslated' to display some information about "what happens when I click on this element?".

You must specify both of the strings. You can only use one and specify an empty string ('') for the other one.

When you pass text directly function _() must be used for the text to be marked for translation! Except for empty string.

Parameter "delay" is optional. It is primarily used to specify a zero delay for some game element when the tooltip gives really important information for the game - but remember: no essential information must be placed in tooltips as they won't be displayed in some browsers (see [[BGA_Studio_Guidelines|Guidelines]]).

Example:
<pre>
this.addTooltip( 'cardcount', _('Number of cards in hand'), '' );
</pre>

Note: this generates static tooltip and attaches to existing dom element, if you need to generate tooltip more dynamically you have to call that method every time information about object is updated or use completely different tehnique, see dynamic tooltips below.

'''this.addTooltipHtml(nodeId: string, html: string, delay?: number): void'''

Add an HTML tooltip to the DOM node (for more elaborate content such as presenting a bigger version of a card).

'''this.addTooltipToClass(cssClass: string, helpStringTranslated: string, actionStringTranslated: string, delay?: number ): void'''

Add a simple text tooltip to all the DOM nodes set with this cssClass. See more details above for this.addTooltip.
this.addTooltipToClass( 'meeple', _('This is A Meeple'), _('Click to tickle') );

IMPORTANT: all concerned nodes must exist and have IDs to get tooltips.

'''this.addTooltipHtmlToClass(cssClass: string, html: string, delay?: number): void'''

Add an HTML tooltip to to all the DOM nodes set with this cssClass (for more elaborate content such as presenting a bigger version of a card).

IMPORTANT: all concerned nodes must exist and have IDs to get tooltips.

=== Removing static tooltips ===

'''this.removeTooltip(nodeId: string): void'''

Remove a tooltip from the DOM node with given id.

=== Advanced tooltips ===

'''force tooltip to open'''

If you want to force tooltip to open in reaction to some other action, i.e. click you can do this

this.tooltips[id].open(id)

where id is the id of the tooltip node where tooltip was installed.

'''dynamic tooltips'''

See [[BGA_Studio_Cookbook#Dynamic_tooltips]]

'''tooltips on mobile'''

Tooltips is very unreliable on mobile, it is recommended to implement some other method to obtaining same information,
such as simple click handler in dedicated "Help" mode or provide dedicated clickable areas such as corner of card.

== Warning messages ==

Sometimes, there is something important that is happening in the game and you have to make sure all players get the message. Most of the time, the evolution of the game situation or the game log is enough, but sometimes you need something more visible.

Ex: someone fulfills one of the end of the game conditions, so this is the last turn.

'''this.showMessage(msg: string, type: string): void'''

showMessage shows a message in a big rectangular area on the top of the screen of the current player, and it dissapears after few seconds (also it will be in the log in some cases).

* "msg" is the string to display. It should be translated.
* "type" can be set to "info", "error", "only_to_log" or custom string. If set to "info", the message will be an informative message on a white background. If set to "error", the message will be an error message on a red background and it will be added to log. If set to "only_to_log", the message will be added to the game log but will not popup at the top of the screen.
If set to custom string, it will be transparent, to use custom type define "head_xxx" in css, where xxx is the type. For example if you want yellow warning, use "warning" as type and add this to css:
.head_warning {
background-color: #e6c66e;
}

Important: the normal way to inform players about the progression of the game is the game log. The "showMessage" is intrusive and should not be used often.

<pre>
notif_messageinfo: function(notif) {
if (!g_archive_mode) {
var message = this.format_string_recursive(notif.log, notif.args);
this.showMessage(_('Announcement:') + " " + message, 'info');
}
},
</pre>

Show message could be used on the client side to prevent user wrong moves before it is send to server.
Example from 'battleship':
<pre>
onGrid: function(event) {
if (checkIfPlayerTriesToFireOnThemselves(event)) {
this.showMessage(_('This is your own board silly!'), 'error');
return;
}
...
},
</pre>

'''this.showMoveUnauthorized(): void'''

Shows predefined user error that move is unauthorized now

<pre>
onPet: function(event) {
if (checkPet(event)==false) {
this.showMoveUnauthorized();
return;
}
...
},
</pre>

== Dialogs ==

=== Confirmation dialog ===

When an important action with a lot of consequences is triggered by the player, you may want to propose a confirmation dialog.

CAREFUL: the general guideline of BGA is to AVOID the use of confirmation dialogs. Confirmation dialogs slow down the game and bother players. The players know that they have to pay attention to each move when they are playing online.

The situations where you should use a confirmation dialog are the following:
* It must not happen very often during a game.
* It must be linked to an action that can really "kill a game" if the player does not pay attention.
* It must be something that can be done by mistake (ex: a link on the action status bar).

'''this.confirmationDialog(message: string, yesHandler: (param: any) => void, noHandler?: (param: any) => void, param?: any): void'''

* message - message will be shown to user, use _() to translate
* yesHandler - non-optional handler to be called on yes
* noHandler - optional handler to called on no
* param - if specified, it will be passed to both handlers
NOTE: this is async function, it does not return anything and you should not do anything after, you must do everything in handlers

How to display a confirmation dialog:
<pre>
this.confirmationDialog(_("Are you sure you want to bake a pie?"), () => {
this.bakeThePie();
});
return; // nothing should be called or done after calling this, all action must be done in the handler
</pre>
With param and both handlers
<pre>
this.confirmationDialog(_("Are you sure you want to bake a pie?"),
(ingredient) => this.bakeThePie(ingredient),
(ingredient) => console.log(`cancelled baking of ${ingredient}`),
'apple');
</pre>

=== Multiple choice dialog ===

You can use this dialog to give user a choice with small amount of options

'''this.multipleChoiceDialog(message: string, choices: string[], callback: (choice: number) => void): void'''
* message - message will be shown to user, use _() to translate
* choices - array of choices
* callback - non-optional handler to be called on choice made, the choice parameter is the INDEX of the choice from the array of choices

NOTE: this is async function, it does not return anything and you should not do anything after, you must do everything in handlers
NOTE: there is no cancel handler, so make sure you gave user a choice to get out of it

Example:
<pre>
const keys = ["0", "1", "5", "10"];
this.multipleChoiceDialog(_("How many bugs to fix?"), keys, (choice) => {
if (choice==0) return; // cancel operation, do not call server action
var bugchoice = keys[choice]; // choice will be 0,1,2,3 here
this.bgaPerformAction("fixBugs", { number: bugchoice });
});
return; // must return here
</pre>

=== Generic Dialogs ===

As a general rule, you shouldn't use dialogs windows.

BGA guidelines specify that all game elements should be displayed on the main screen. Players can eventually scroll down to see game elements they don't need to see anytime, and you may eventually create anchors to move between game area section. Of course dialogs windows are very practical, but the thing is: all players know how to scroll down, and not all players know how to show up your dialog window. In addition, when the dialog shows up, players can't access the other game components.

Sometimes although, you need to display a dialog window. Here is how you do this:

// Create the new dialog over the play zone. You should store the handler in a member variable to access it later
this.myDlg = new ebg.popindialog();
this.myDlg.create( 'myDialogUniqueId' );
this.myDlg.setTitle( _("my dialog title to translate") );
this.myDlg.setMaxWidth( 500 ); // Optional

// Create the HTML of my dialog.
// The best practice here is to use [[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl#Javascript_templates|Javascript templates]]
var html = this.format_block( 'jstpl_myDialogTemplate', {
arg1: myArg1,
arg2: myArg2,
...
} );

// Show the dialog
this.myDlg.setContent( html ); // Must be set before calling show() so that the size of the content is defined before positioning the dialog
this.myDlg.show();

// Now that the dialog has been displayed, you can connect your method to some dialog elements
// Example, if you have an "OK" button in the HTML of your dialog:
dojo.connect($('my_ok_button'), 'onclick', this, (event) => {
event.preventDefault();
this.myDlg.destroy();
});

If necessary, you can remove the default top right corner 'close' icon, or replace the function called when it is clicked:
// Removes the default close icon
this.myDlg.hideCloseIcon();

// Replace the function call when it's clicked
this.myDlg.replaceCloseCallback((event) => { ... });

=== Scoring dialogs ===

Sometimes at the end of a round you want to display a big table that details the points wins in each section of the game.

Example: in Hearts game, we display at the end of each round the number of "heart" cards collected by each player, the player who collected the Queen of Spades, and the total number of points loose by each player.

Scoring dialogs are managed entirely on '''PHP side''', but they are described here as their effects are visible only on client side.

Displaying a scoring dialog is quite simple and is using a special notification type: "tableWindow":
<pre>
// on PHP side:
$this->notifyAllPlayers( "tableWindow", '', array(
"id" => 'finalScoring',
"title" => clienttranslate("Title of the scoring dialog"),
"table" => $table
));
</pre>

The "table" argument is a 2 dimensional PHP array that describes the table you want to display, line by line and column by column.

Example: display an 3x3 array of strings
<pre>
$table = [
[ "one", "two", "three" ], // This is my first line
[ "four", "five", "six" ], // This is my second line
[ "seven", "height", "nine" ] // This is my third line
];
</pre>

As you can see above, in each "cell" of your array you can display a simple string value. But you can also display a complex value with a template and associated arguments like this:
<pre>
$table = [
[ "one", "two", [ "str" => clienttranslate("a string with an ${argument}"), "args" => [ 'argument' => 'argument_value' ] ] ],
[ "four", "five", "six" ],
[ "seven", "height", "nine" ]
];
</pre>

This is especially useful when you want to display player names with colors. Example from "Hearts":
<pre>
$firstRow = [ '' ];
foreach( $players as $player_id => $player ) {
$cell = [ 'str' => '${player_name}',
'args' => [ 'player_name' => $player['player_name'] ],
'type' => 'header'
];
$firstRow[] = $cell;
}
$table[] = $firstRow;
...
</pre>

You can also use three extra attributes in the parameter array for the notification:
* '''header''': the content for this parameter displays before the table (also, the html will be parsed and player names will be colored according to the current game colors).
* '''footer''': the content for this parameter displays after the table (no parsing for coloring the player names)
* '''closing''': if this parameter is used, a button will be displayed with this label at the bottom of the popup and will allow players to close it (more easily than by clicking the top right 'cross' icon).

<pre>
$this->notifyAllPlayers( "tableWindow", '', [
"id" => 'finalScoring',
"title" => clienttranslate("Title of the scoring dialog"),
"table" => $table,
"header" => ['str' => clienttranslate('Table header with parameter ${number}'),
'args' => [ 'number' => 3 ],
],
"footer" => '<div class="myfoot"></div>',
"closing" => clienttranslate( "Closing button label" )
] );
</pre>

Note: currently id is not used - so you cannot access resulting div by id on js side

Note: any traslatable string have to be wrapped by clienttranslate() on top level OR it has to be recursive template.

DO NOT DO THIS:
<pre>
"footer" => '<div>'.clienttranslate( "The end" ).'</div>', // this will not work for translations!!!
</pre>

=== Scoring animated display ===

Sometimes, you may want to display a score value over an element to make the scoring easier to follow for the players (Terra Mystica final scoring for example).
You can do it with:

'''this.displayScoring(anchor_id: string, color: string, score: number | string, duration?: number, offset_x?: number, offset_y?: number): void'''

'''anchor_id''': ID of the html element to place the animated score onto (without the '#')

'''color''': hexadecimal RGB representation of the color (should be the color of the scoring player), but without a leading '#'. For instance, 'ff0000' for red.

'''score''': numeric score to display, prefixed by a '+' or '-'

'''duration''': animation duration in milliseconds (optional, default is 1000)

'''offset_x''' and '''offset_y''': if both offset_x and offset_y are defined and not null, apply the following offset (in pixels) to the scoring animation.
Note that the score is centered in the anchor, so the offsets might have to be negative if you calculate the position.

Note: if you want to display successively each score, you can use ''this.notifqueue.setSynchronous()'' function.
<pre>
setupNotifications: function() {
dojo.subscribe( 'displayScoring', this, "notif_displayScoring" );
...
}
...

notif_displayScoring: function(notif) {
const duration = notif.args.duration?notif.args.duration:1000;
this.notifqueue.setSynchronous('displayScoring', duration );
this.displayScoring( notif.args.target, notif.args.color, notif.args.score, duration);
},
</pre>

=== Speech bubble ===

For better interactivity in some games (Love Letter for example), you may use comic book style speech bubbles to express the players voices.
This is done with showBubble:

'''this.showBubble(anchor_id: string, text: string, delay?: number, duration?: number, custom_class?: string): void'''

* anchor_id - where to attach the bubble
* text - what to put in bubble, can be html
* delay - delay in milliseconds (optional, default 0)
* duration - duration of animation in milliseconds (optional, default 3000)
* custom_class - extra class to add to bubble (optional), if you need to override the default bubble style

<pre>
this.showBubble('meeple_2', _('Hello'), 0, 1000, 'pink_bubble');
</pre>

<pre>
notif_speechBubble(notif) {
var html = this.format_string_recursive(notif.args.text, notif.args.args);
this.showBubble(notif.args.target, html, notif.args.delay ?? 0, notif.args.duration ?? 1000);
},
</pre>

'''Warning''': if your bubble could overlap other active elements of the interface (buttons in particular), as it stays in place even after disappearing, you should use a custom class to give it the style "pointer-events: none;" in order to intercept click events.

Note: If you want this visually, but want to take complete control over this bubble and its animation (for example to make it permanent) you can just use div with 'discussion_bubble' class on it, and content of div is what will be shown.

== Translations ==

See [[Translations]]

== Players panels ==

=== Update players score ===

The column player_score from the player table is automatically loaded into this.scoreCtrl and therefore into the stars location on the player board. This occurs sometime after the game setup() function. However this score must be updated as the game progresses using notifications.

Note: this.scoreCtrl[player_id] is object of class [[Counter]], you can use other counter API.

Increase a player score (with a positive or negative number):

<pre>
this.scoreCtrl[ player_id ].incValue( score_delta );
</pre>

Set a player score to a specific value:

<pre>
this.scoreCtrl[ player_id ].setValue( new_score );
</pre>

Set a player score to a specific value with animation:

<pre>
this.scoreCtrl[ player_id ].toValue( new_score );
</pre>

Typical usage would be (that will process 'score' notification):
<pre>
setupNotifications : function() {
...
dojo.subscribe('score', this, "notif_score");
},
notif_score: function(notif) {
this.scoreCtrl[notif.args.player_id].setValue(notif.args.player_score);
},
</pre>

=== Adding stuff to player's panel ===

At first, create a new "JS template" string in your template (tpl) file:

(from Gomoku example)
<pre>
var jstpl_player_board = '\<div class="cp_board">\
<div id="stoneicon_p${id}" class="gmk_stoneicon gmk_stoneicon_${color}"></div><span id="stonecount_p${id}">0</span>\
</div>';
</pre>

Then, you add this piece of code in your JS file to add this template to each player panel:

<pre>
// Setting up player boards
for( var player_id in gamedatas.players )
{
var player = gamedatas.players[player_id];

// Setting up players boards if needed
var player_board_div = $('player_board_'+player_id);
dojo.place( this.format_block('jstpl_player_board', player ), player_board_div );
}
</pre>

(Note: the code above is of course from your "setup" function in your Javascript).

Very often, you have to distinguish current player and others players. In this case, you just have to create another JS template (ex: jstpl_otherplayer_board) and use it when "player_id" is different than "this.player_id".

=== Fixing Player Panel heights ===

You may find that the player panels don't automatically resize when adding something to (or removing something from) a player panel while the display is in portrait mode (i.e. the player summary panels are at the top of the screen rather than down the right side).

When this happens, call <pre>this.adaptPlayersPanels();</pre> This recalculates the layout and also adjusts the position of the actionbar for you.

=== Player's panel disabling/enabling ===

'''this.disablePlayerPanel(player_id: number): void'''

Disable given player panel (the panel background become gray).

Usually, this is used to signal that this played passes, or will be inactive during a while.

Note that the only effect of this is visual. There are no consequences on the behaviour of the panel itself.

'''this.enablePlayerPanel(player_id:number): void'''

Enable a player panel that has been disabled before.

'''this.enableAllPlayerPanels(): void'''

Enable all player panels that has been disabled before.

=== Player order ===

'''this.updatePlayerOrdering(): void'''

This function makes sure that player order in player's panel matches this.gamedatas.playerorder and its normally called by framework.
You can call it yoursel if you change this.gamedatas.playerorder from notification.
Also you can override this function to change defaults OR insert a non-player panel [[BGA_Studio_Cookbook#Inserting_non-player_panel]].

=== Counters ===
Note: there is a bga component called "ebg/counter", this API is not using it. These methods below are declared right in the core game. If you need animation for counters use ebg/counter

To use this API just create a counter dom element like this (class does not really matter)
<pre>
<div class="counter" id="bread"></div>
<div class="counter" id="coin"></div>
</pre>
The "bread" will the counter name.

The php code should send all "counters" data from getAllDatas() method like this

game.php
<pre>
protected function getAllDatas() {
// (the key must match counter_name)
$result['counters']=[
'bread' => [
'counter_name' => 'bread',
'counter_value' => 3
],
'coin' => [
'counter_name' => 'coin',
'counter_value' => 5
]
];
return $result;
}
</pre>

'''setCounter(counter_name: stirng, new_value: string | number): void'''

updates the global this.gamedatas.counters and value of node $(counter_name)
<pre>
notif_counter: function(notif) {
this.setCounter(notif.args.counter_name, notif.args.counter_value);
},
</pre>

'''incCounter(counter_name: string, delta: number): void'''
<pre>
notif_counter : function(notif) {
this.incCounter(notif.args.counter_name, notif.args.inc);
},
</pre>

'''updateCounters(counters: object): void'''

Useful for updating game counters in the player panel (such as resources).
'counters' arg is map of counters (the key must match counter_name)
{
'bread': {
'counter_name' : 'bread',
'counter_value' => 3
},
'coin': {
'counter_name' : 'coin',
'counter_value' => 5
}
}
All counters MUST be referenced in this.gamedatas.counters (means they should be send from php) and will be updated.
DOM objects referenced by 'counter_name' will have their innerHTML updated with 'counter_value'.

Usually you call this from notification

<pre>
notif_counter : function(notif) {
this.updateCounters(notif.args.counters);
},
</pre>

== BGA GUI components ==

BGA framework provides some useful ready-to-use components for the game interface:

[[Studio#BGA_Studio_game_components_reference]]

Note that each time you are using an additional component, you must declare it at the top of your Javascript file in the list of modules used.

Example if you are using "ebg.stock":
<pre>
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/stock" /// <=== we are using ebg.stock module
],
</pre>

== BGA Buttons ==

=== Basic Button ===

'''this.addActionButton(id: string, label: string, method: string | eventhandler, destination?: string, blinking?: boolean, color?: string): void'''

You can use this method to add an action button in the main action status bar (or other places).

Arguments:
* id: an element ID that should be unique in your HTML DOM document.
* label: the text of the button. Should be translatable (use _() function). Note: this can also be any html, such as "<div class='brick'></div>", see example below on how to make image action buttons.
* method: the name of your method that must be triggered when the player clicks on this button (can be name of the method on game class or handler).
* destination (optional): id of parent on where to add button, ONLY use in rare cases if location is not action bar. Use '''null''' as value if you need to specify other arguments.
* blinking (optional): if set to '''true''', the button is going blink to catch player's attention. Please DO NOT abuse blinking button. If you need button to blink after some time passed add class 'blinking' to the button later.
* color: could be '''blue''' (default), '''red''','''gray''' or '''none'''.

You should only use this method in your "onUpdateActionButtons" method. Usually, you use it like this:

<pre>
onUpdateActionButtons: function( stateName, args ) {
if (this.isCurrentPlayerActive()) {
switch( stateName ) {
case 'giveCards':
this.addActionButton( 'giveCards_button', _('Give selected cards'), 'onGiveCards' );
this.addActionButton( 'pass_button', _('Pass'), () => this.bgaPerformAction('actPass') );
break;
}
}
},
</pre>

In the example above, we are adding a "Give selected cards" button in the case we are on game state "giveCards". When player clicks on this button, it triggers our "onGiveCards" method.

Example using blinking red button:
<pre>
this.addActionButton( 'button_confirm', _('Confirm?'), 'onConfirm', null, true, 'red');
</pre>

If you want to call the handler with arguments, you can use arrow functions, like this:
<pre>
this.addActionButton( 'commit_button', _('Confirm'), () => this.onConfirm(this.selectedCardId), null, false, 'red');
</pre>

=== Image Button ===

You can use the same method, but add extra class to a button to disable the padding and style it, i.e.
<pre>
this.addActionButton( 'button_brick', '<div class="brick"></div>', ()=>{... on brick ...}, null, null, 'gray');
dojo.addClass('button_brick','bgaimagebutton');
</pre>

where

<pre>
.bgaimagebutton {
padding: 0px 12px;
min-height: 28px;
border: none;
}
</pre>

If you use this a lot, you can define a helper function, i.e.
<pre>
/**
* This method can be used instead of addActionButton, to add a button which is an image (i.e. resource). Can be useful when player
* need to make a choice of resources or tokens.
*/
addImageActionButton: function(id, div, handler, bcolor, tooltip) {
if (typeof bcolor == "undefined") {
bcolor = "gray";
}
// this will actually make a transparent button id color = gray
this.addActionButton(id, div, handler, null, false, bcolor);
// remove border, for images it better without
dojo.style(id, "border", "none");
// but add shadow style (box-shadow, see css)
dojo.addClass(id, "shadow bgaimagebutton");
// you can also add additional styles, such as background
if (tooltip) {
dojo.attr(id, "title", tooltip);
}
return $(id);
},
</pre>

=== Disabling Button ===

You can disable the '''bgabutton''' by adding the css class '''disabled''' in you js. The disabled button is still visible but is grey and not clickable.
For example in the '''onUpdateActionButtons''' :
<pre>
this.addActionButton('play_button_id', _('Play 1 to 3 cards'), 'playFunctionButton');
if (condition) {
dojo.addClass('play_button_id', 'disabled');
}
</pre>

=== Custom Buttons ===

You can create a custom button, but the BGA framework provides a standard button that requires only .css classes: '''bgabutton''' and '''bgabutton_${color}'''.

'''Examples:'''

<pre>
<a href="#" id="my_button_id" class="bgabutton bgabutton_blue"><span>My blue button</span></a>

<a href="#" id="my_button_id" class="bgabutton bgabutton_red bgabutton_big"><span>My big red button</span></a>
</pre>

'''Note''': To see it in action, check out ''Coloretto''.

=== Button outside of action bar ===

Use addActionButton() method with destination argument set
<pre>
this.addActionButton( 'commit_button', _('Confirm'), 'onConfirm', 'player_board', true, 'red');
</pre>

in example above the button will be place on object with id 'player_board'

== Image loading ==

See also [[Game_art:_img_directory]].

'''Be careful''': by default, ALL images of your img directory are loaded on a player's browser when he loads the game. For this reason, don't let in your img directory images that are not useful, otherwise it's going to slowdown the game load.

'''this.dontPreloadImage(image_file_name: string)'''

Using dontPreloadImage, you tell the interface to not preload a specific image in your img directory.

Example of use:
<pre>
this.dontPreloadImage( 'cards.png' );
</pre>

This is particularly useful if for example you have 2 different themes for a game. To accelerate the loading of the game, you can specify to not preload images corresponding to the other theme.

Another example of use: in "Gosu" game with Kamakor extension, you play with 5 sets of cards among 10 available. Cards images are organized by sets, and we only preload the images corresponding to the 5 current sets with '''ensureSpecificGameImageLoading( image_file_names_array )'''.
<pre>
// By default, do not preload anything
this.dontPreloadImage( 'cards.png' );
this.dontPreloadImage( 'clan1.png' );
this.dontPreloadImage( 'clan2.png' );
this.dontPreloadImage( 'clan3.png' );
this.dontPreloadImage( 'clan4.png' );
this.dontPreloadImage( 'clan5.png' );
this.dontPreloadImage( 'clan6.png' );
this.dontPreloadImage( 'clan7.png' );
this.dontPreloadImage( 'clan8.png' );
this.dontPreloadImage( 'clan9.png' );
this.dontPreloadImage( 'clan10.png' );
var to_preload = [];
for( i in this.gamedatas.clans )
{
var clan_id = this.gamedatas.clans[i];
to_preload.push( 'clan'+clan_id+'.png' );
}

this.ensureSpecificGameImageLoading( to_preload );

</pre>

'''Note:''' You don't need to specify to not preload game box images (game_box.png, game_box75.png...) since they are not preloaded by default.

'''this.ensureSpecificGameImageLoading(list: string[])'''

This is oppostive of dontPreloadImage - its ensure specific images is loaded. Note: only makes sense if preload list is empty, otherwise everything is loaded anyway

'''load specific images'''
All images that will be preloaded stored in g_img_preload. If you want to override it directly - there is no API, but you can do this in GAME constructor

g_img_preload = ['tokens.png', 'trains.png', 'loc_plan.png', 'eng.png', 'eng-back.png'];

You can also set it to empty array and call ensureSpecificGameImageLoading() on specific images

== Sounds ==

Add a custom sound and make it load with your interface:

Add this in your template (.tpl) file:
<pre>
<audio id="audiosrc_<gamename>_<yoursoundname>" src="{GAMETHEMEURL}img/<gamename>_<yoursoundname>.mp3" preload="none" autobuffer></audio>
<audio id="audiosrc_o_<gamename>_<yoursoundname>" src="{GAMETHEMEURL}img/<gamename>_<yoursoundname>.ogg" preload="none" autobuffer></audio>
</pre>

Note: this is a requirement to provide both a mp3 and a ogg file with the names <code><gamename>_<yoursoundname>[.ogg][.mp3]</code>.

Play the sound (from your .js file):

<pre>
playSound('<gamename>_<yoursoundname>'); // do not add 'this.' - its a global function
</pre>

Disable the standard "move" sound for this move (to replace it with your custom sound):

Add this to your notification handler:

<pre>
this.disableNextMoveSound();
</pre>

Note: it only disable the sound for the next move.

== Title bar and states ==

=== Client states ===

Client states is a way to simulate the state transition but without actually going
to server. It is usefull when you need to ask user multiple questions before you
send things to server

'''this.setClientState(newState: string, args: object)'''

Example:
this.setClientState("client_playerPicksLocation", {
descriptionmyturn : _("${you} must select location"),
});

For more information see [[BGA_Studio_Cookbook#Multi_Step_Interactions:_Select_Worker.2FPlace_Worker_-_Using_Client_States]]

'''this.restoreServerGameState()'''
If you are in client state it will restore the current server state (cheap undo)

'''this.on_client_state'''
Boolean indicating that we are in client state

=== Title bar ===
If you simply want to show something in title bar you can do it directly
$('pagemaintitletext').innerHTML = text;

This however will not work with parameters and will not draw You in color,
if you want to do proper args rendering use method below

;'''this.removeActionButtons()'''
Removes all buttons from title bar

;'''this.updatePageTitle()'''
:This function allows to update the current page title and turn description according to the game state arguments. If the current game state description this.gamedatas.gamestate.descriptionmyturn is modified before calling this function it allows to update the turn description without changing state. This will handle arguments substitutions properly.

Note: this functional also will calls this.onUpdateActionButtons, if you want different buttons then state defaults, use method in example to replace them, if it becomes too clumsy use client states (see above)

Example from Terra Mystica:
<pre>
onClickFavorTile: function( evt ) {
...
if ( ... ) {
this.gamedatas.gamestate.descriptionmyturn = _('Special action: ') + _('Advance 1 space on a Cult track');
this.updatePageTitle();
this.removeActionButtons();
this.addActionButton( ... );
...
return;
}
...

}
</pre>

== User preferences ==
'''this.getGameUserPreference(pref_id)'''

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

'''this.setGameUserPreference(pref_id, value)'''

Programmatically change a user preference. It will have the same effect as if the player changed the value in the select combo box, in the top-right menu.

'''this.onGameUserPreferenceChanged'''

A callback you can define if you want to be notified when a user changes a user preference.

Example:<pre>
onGameUserPreferenceChanged: function(pref_id, pref_value) {
switch (pref_id) {
case 201:
document.getElementsByTagName('html')[0].classList.toggle('dark-background', pref_value == 2);
break;
}
}
</pre>

== Other useful stuff ==

'''dojo.hitch'''

With dojo.hitch, you can create a callback function that will run with your game object context whatever happen.

Typical example: display a BGA confirmation dialog with a callback function created with dojo.hitch:

<pre>
this.confirmationDialog( _('Are you sure you want to make this?'), dojo.hitch( this, function() {
this.bgaPerformAction('makeThis');
} ) );
</pre>

In the example above, using dojo.hitch, we ensure that the "this" object will be set when the callback is called.

NOTE: In modern JS there are lambdas that eliminate need for that, the example above will look like this
<pre>
this.confirmationDialog( _('Are you sure you want to make this?'), () => this.bgaPerformAction( 'makeThis') );
</pre>

;'''onScreenWidthChange()'''
:This function can be overridden in your game to manage some resizing on the client side when the browser window is resized. This function is also triggered at load time, so it can be used to adapt to the :viewport size at the start of the game too.

; this.bRealtime
: Return true if the game is in realtime. Note that having a distinct behavior in realtime and turn-based should be exceptional.

; g_replayFrom
: Global contains replay number in live game, it is set to undefined (i.e. not set) when it is not a replay mode, so consequentially the good check is '''typeof g_replayFrom != 'undefined'''' which returns true if the game is in replay mode <i>during the game</i> (the game is ongoing but the user clicked "replay from this move" in the log)

; g_archive_mode
: Returns true if the game is in archive mode <i>after the game</i> (the game has ended)

; this.instantaneousMode
: Returns true during replay/archive mode if animations should be skipped. Only needed if you are doing custom animations. (The BGA-provided animation functions like <i>this.slideToObject()</i> automatically handle instantaneous mode.)
: Technically, when you click "replay from move #20", the system replays the game from the very beginning with moves 0 - 19 happening in instantaneous mode and moves 20+ happening in normal mode.

; g_tutorialwritten
: Returns an object like the below if the game is in tutorial mode, or undefined otherwise. Tutorial mode is a special case of archive mode where comments have been added to a previous game to teach new players the rules.
{
author: "91577332",
id: "576",
mode: "view"
status: "alpha"
version_override: null
viewer_id: "84554161"
}

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

[[Category:Studio]]

Game interface logic: Game.js

2024-09-25T18:21:19Z

Sguzzer Gunayer: /* Scoring dialogs */

{{Studio_Framework_Navigation}}

__TOC__

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

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

== File structure ==

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

Here is the basic structure:

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

More details:

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

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

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

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

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

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

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

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

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

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

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

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

== Dojo framework ==

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

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

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

== Javascript minimization (after July 2020) ==

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

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

== Accessing Players Information ==

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

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

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

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

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

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

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

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

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

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

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

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

== Accessing and manipulating the DOM ==

=== Element by Id ===

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

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

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

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

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

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

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

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

=== Style ===

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

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

Examples:

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

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

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

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

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

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

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

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

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

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

=== Classes ===

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

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

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

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

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

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

Example from ''Reversi'':

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

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

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

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

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

'''Vanilla JS classList'''

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

=== Attributes ===

;dojo.attr

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

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

'''Vanilla JS attr'''

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

=== Queries ===

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

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

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

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

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

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

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

'''Vanilla JS query'''

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

=== Creating and Destroying elements ===

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

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

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

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

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

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

Create element

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

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

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

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

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

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

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

const div = ``;
'''this.format_string_recursive'''

This bga function is similar to this.format_string but is capable of processing recursive argument structures and translations. It is used to format server notifications.

TODO: find better place for these function docs

=== Moving elements ===

'''dojo.place(node: string | Element, refNode: ElementOrId, pos?: string | number): Element'''

dojo.place is the best function to insert HTML code somewhere in your game interface without breaking something. It is much better to use than the '''innerHTML=''' method if you must insert HTML tags and not only values.

node: can be a string or a DOM node. If it is a string starting with “<”, it is assumed to be an HTML fragment, which will be created. Otherwise it is assumed to be an id of a DOM node.

<pre>
// Insert your HTML code as a child of a container element
dojo.place( "<div class='foo'></div>", "your_container_element_id" );
</pre>

pos: optional argument. Can be a number or one of the following strings: “before”, “after”, “replace”, “only”, “first”, or “last”. If omitted, “last” is assumed.

* "replace": replace the container element with my_node element
* "first": places the node as a child of the reference node. The node is placed as the first child.
* "last" (default): places the node as a child of the reference node. The node is placed as the last child.
* "before": places the node right before the reference node.
* "after": places the node right after the reference node.
* "only": replaces all children of the reference node with the node.

this parameter can be a positive integer. In this case, the node will be placed as a child of the reference node with this number (counting from 0). If the number is more than number of children, the node will be appended to the reference node making it the last child.

<pre>
// Replace all children of container with my_node
dojo.place( $('my_node'), "your_container_element_id", "only" );
</pre>

See also full doc on dojo.place: [https://dojotoolkit.org/reference-guide/1.7/dojo/place.html]

Usually, when you want to insert some piece of HTML in your game interface, you should use "[[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl#Javascript_templates|Javascript templates]]".

But you can also relocate elements like that. Note: it won't animate if you do that.

'''this.placeOnObject(mobile_obj: ElementOrId, target_obj: ElementOrId): void'''

places mobile_obj on target_obj, set the absolute positions and centers the mobile_obj on target_obj,
effect is immediate

This is not really an animation, but placeOnObject is frequently used before starting an animation.

Example:
<pre>
// (We just created an object "my_new_token")

// Place the new token on current player board
this.placeOnObject( "my_new_token", "overall_player_board_"+this.player_id );

// Then slide it to its position on the board
this.slideToObject( "my_new_token", "a_place_on_board" ).play();
</pre>

'''this.placeOnObjectPos(mobile_obj: ElementOrId, target_obj: ElementOrId, target_x: number, target_y: number): void'''

This method works exactly like placeOnObject, except than you can specify some (x,y) coordinates (in px). This way, the center of "mobile_obj" will be placed to the specified x,y position relatively to the center of "target_obj".

''Note: the placement works differently from this.slideToObjectPos'', since coordinates are calculated based on the center of objects.

'''this.attachToNewParent(mobile_obj: ElementOrId, target_obj: ElementOrId): void'''

With this method, you change the HTML parent of "mobile_obj" element without moving it.
"target_obj" is the new parent of this element. The beauty of
attachToNewParent is that the mobile_obj element DOES NOT MOVE during this process.

What happens is that the method calculate a relative position of mobile_obj to make sure it does not move after the HTML parent changes.

Why using this method?

Changing the HTML parent of an element can be useful for the following reasons:
* When the HTML parent moves, all its child are moving with them. If some game elements is no more linked with a parent HTML object, you may want to attach it to another place.
* The z_order (vertical order of display) depends on the position in the DOM, so you may need to change the parent of some game elements when they are moving in your game area.

'''CAREFUL''': this function destroys original object and places a clone onto a new parent, this will break all references to this HTML element (ex: dojo.connect).
If you need version that does not destroy the object but the same otherwise see [[BGA_Studio_Cookbook#Attach_to_new_parent_without_destroying_the_object]]

== Animations ==

===Dojo Animations===

BGA animations is based on Dojo Animation ([http://dojotoolkit.org/documentation/tutorials/1.8/animation/ see tutorial here]).

However, most of the time, you can just use methods below, which are built on top of Dojo Animation.

Note: one interesting method from Dojo that could be useful from time to time is "Dojo.Animation". It allows you to make any CSS property "slide" from one value to another.

Note 2: the slideTo methods are not compatible with CSS transform (scale, zoom, rotate...). If possible, avoid using CSS transform on nodes that are being slided. Eventually, the only possible solution to make these 2 compatible is to disable all CSS transform properties, use slideToObjectPos/placeOnObjectPos, and then apply them again.

===Sliding===

'''this.slideToObject(mobile_obj: ElementOrId, target_obj: ElementOrId, duration?: number, delay?: number): Animation'''

You can use slideToObject to "slide" an element to a target position.

Sliding element on the game area is the recommended and the most used way to animate your game interface. Using slides allow players to figure out what is happening on the game, as if they were playing with the real boardgame.

The parameters are:
* mobile_obj: the ID of the object to move. This object must be "relative" or "absolute" positioned.
* target_obj: the ID of the target object. This object must be "relative" or "absolute" positioned. Note that it is not mandatory that mobile_obj and target_obj have the same size. If their size are different, the system slides the center of mobile_obj to the center of target_obj.
* duration: (optional) defines the duration in millisecond of the slide. The default is 500 milliseconds.
* delay: (optional). If you defines a delay, the slide will start only after this delay. This is particularly useful when you want to slide several object from the same position to the same position: you can give a 0ms delay to the first object, a 100ms delay to the second one, a 200ms delay to the third one, ... this way they won't be superposed during the slide.

BE CAREFUL: The method returns an dojo.fx animation, so you can combine it with other animation if you want to. It means that you have to call the "play()" method, otherwise the animation WON'T START.

Example:
<pre>
this.slideToObject( "some_token", "some_place_on_board" ).play();
</pre>

'''this.slideToObjectPos(mobile_obj: ElementOrId, target_obj: ElementOrId, target_x: number, target_y: number, duration?: number, delay?: number): Animation'''

This method does exactly the same as "slideToObject", except than you can specify some (x,y) coordinates. This way, "mobile_obj" will slide to the specified x,y position relatively to "target_obj".

Example: slide a token to some place on the board, 10 pixels from the top:
<pre>
this.slideToObjectPos( "some_token", "some_place_on_board", 0, 10 ).play();
</pre>

'''this.slideTemporaryObject(mobile_obj_html: string, parent: ElementOrId, from: ElementOrId, to: ElementOrId, duration?: number, delay?: number): Animation'''

This method is useful when you want to slide a temporary HTML object from one place to another. As this object does not exists before the animation and won't remain after, it could be complex to create this object (with dojo.place), to place it at its origin (with placeOnObject) to slide it (with slideToObject) and to make it disappear at the end.

slideTemporaryObject does all of this for you:
* mobile_obj_html is a piece of HTML code that represent the object to slide.
* parent is the ID of an HTML element of your interface that will be the parent of this temporary HTML object.
* from is the ID of the origin of the slide.
* to is the ID of the target of the slide.
* duration/delay works exactly like in "slideToObject"

Example:
<pre>
this.slideTemporaryObject( '<div class="token_icon"></div>', 'tokens', 'my_origin_div', 'my_target_div' ).play();
</pre>

===Destroy===
'''this.slideToObjectAndDestroy(mobile_obj: ElementOrId, target_obj: ElementOrId, duration?: number, delay?: number): void'''

This method is a handy shortcut to slide an existing HTML object to some place then destroy it upon arrival. It can be used for example to move a victory token or a card from the board to the player panel to show that the player earns it, then destroy it when we don't need to keep it visible on the player panel.

It works the same as this.slideToObject and takes the same arguments, but it starts the animation.

CAREFUL: Make sure nothing is creating the same object at the same time the animation is running, because this will cause some random disappearing effects

Example:
<pre>
this.slideToObjectAndDestroy( "some_token", "some_place_on_board", 1000, 0 );
</pre>

'''this.fadeOutAndDestroy( node: string | Element, duration?: number, delay?: number):''' '''void'''

This function fade out the target node, then destroy it. Its starts the animation.
* duration/delay works exactly like in "slideToObject"

Example:
<pre>
this.fadeOutAndDestroy( "a_card_that_must_disappear" );
</pre>

CAREFUL: the HTML node still exists until during few milliseconds, until the fadeOut has been completed.
Make sure nothing is creating same object at the same time as animation is running, because you will be some random dissapearing effects

===Rotating elements===

This example combines "Dojo.Animation" method and a CSS property transform that allow you to rotate the element.
<pre>
// node is Element we rotating
var animation = new dojo.Animation({
curve: [fromDegree, toDegree],
onAnimate: (v) => {
node.style.transform = 'rotate(' + v + 'deg)';
}
});

animation.play();
</pre>

BGA has its own interface to rotate

'''this.rotateTo(node: string | Element, degree: number): void'''

It starts the animation, and stored the rotation degree in the class, so next time you rotate object - it is additive.
There is no animation hooks in this one, if you need to change any parameters use dojo animation above.

There is also '''rotateInstantTo''' with same signature which does not animate

===Animation Callbacks===

If you wish to run some code only after an animation has completed you can do this by linking a callback method to 'onEnd'.

<pre>
var animation_id = this.slideToObject( mobile_obj, target_obj, 500 );
dojo.connect(animation_id, 'onEnd', () => {
// do something here
});
animation_id.play();
</pre>

If you wish to call a second animation after the first (rather than general code) then you can use a dojo animation chain (see tutorial referenced above).

== Players input ==

=== Connecting ===
'''dojo.connect(element: Element, event: string, context: object, method: eventHandler): any'''

'''dojo.connect(element: Element, event: string, handler: eventHandler): any'''

Used to associate a player event with one of your notification methods.

Example: associate a click on an element ("my_element") with one of our methods ("onClickOnMyElement"):
<pre>
dojo.connect( $('my_element'), 'onclick', this, 'onClickOnMyElement' );
</pre>

Same idea but based on query (i.e. all element of 'pet' class)
dojo.query(".pet").connect('onclick', this, 'onPet');

Note: if you need to disconnect the handler you have to store handler returned from this method, i.e.

<pre>
var handler = dojo.connect(...);
...
dojo.disconnect(handler);
</pre>

If you don't store the handler - you have to destroy the object to disconnect it

Typical function that implements the input handler will look like this

<pre>
onPet: function(event) {
var id = event.currentTarget.id;
console.log('onPet ' + id);
dojo.stopEvent(event);
if (this.gamedatas.gamestate.name == 'playerTurnPet') {
this.bgaPerformAction('actPlayPet', {card: id});
} else {
this.showMoveUnauthorized();
}
}
</pre>

'''this.connect(element: ElementOrId, event: string, method: eventHandler): void'''

Used to associate a player event with one of your notification methods.

this.connect( $('my_element'), 'onclick', 'onClickOnMyElement' );

Or you can use an in-place handler

this.connect( $('my_element'), 'onclick', (e) => { console.log('boo'); } );

Note that this function stores the connection handler. That is the only real difference between '''this.connect''' and '''dojo.connect'''. If you plan to destroy the element you connected, you '''must''' call this.disconnect() to prevent memory leaks.
This function is mainly for permanent objects - if you just want to connect the temp object you should probably not use this method but use dojo.connect which won't require any clean-up.

'''this.connectClass(cssClassName: string, event: string, method: eventHandler): void'''

Same as connect(), but for all the nodes set with the specified cssClassName.
this.connectClass('pet', 'onclick', 'onPet');
'''this.disconnect(element: ElementOrId, event: string): void'''

Disconnect event handler (previously registered with this.connect or this.connectClass).

this.disconnect( $('my_element'), 'onclick');

Note: dynamic connect/disconnect is for advanced cases ONLY, you should always connect elements statically if possible, i.e. in setup() method.

'''this.disconnectAll(): void'''

Disconnect all previously registed event handlers (registered via this.connect or this.connectClass)

this.disconnectAll();

=== Actions ===

'''this.bgaPerformAction(action: string, args?: object, options: object = { lock: true, checkAction: true }): Promise<void>'''

Triggers an action on the backend. This is a combination of checkAction and ajaxcall, returning a Promise which resoves when ajaxcall ends.

This method must be used to send a player input to the game server. '''It should not be triggered programmatically''', especially not in loops, in callbacks, in notifications, or in onEnteringState/onUpdateActionButtons/onLeavingState, in order not to create race conditions or break replay game and tutorial features. It should be used only in reaction to a user action in the interface.

* action: name of the action, as it is written in "possibleactions" of the current state.
* args: an object containing the call parameters to send to the action
* options: options to tweak the call with some defaults. Default is <code>{ lock: true, checkAction: true }</code>.

Example of a standard call without args:
this.bgaPerformAction('pass');

Example of a standard call with action args:
this.bgaPerformAction('actPlayCard', { id: this.selectedCardId });

Example of a call without checking action (because player is inactive in a multiactive state):

this.bgaPerformAction('actChangeMind', {}, { checkAction: false });

Example of a call without lock (because of a special action not directly related to the game flow):

this.bgaPerformAction('actSetAutoBid', { alwaysBidUntil: 500 }, { lock: false, checkAction: false });

Example of call with reaction to exception:
this.bgaPerformAction('actPlayCard', { id: this.selectedCardId }).catch(()=>{ this.selectedCardId = undefined; });

Example of call with reaction to success:
this.bgaPerformAction('actPlayCard', { id: this.selectedCardId }).then(()=>{ this.unselectAll(); });

'''this.ajaxcall(url, parameters, obj_callback, callback, callback_anycase?, ajax_method?: string)'''

''Note: bgaPerformAction is a simpler way to use ajax calls, ajaxcall stays in the doc for legacy reasons only and should not be used in new projects.''

Same warning as '''this.bgaPerformAction''' about using on user action only.

* url: the url of the action to perform. For a game, it must be: "/<mygame>/<mygame>/myAction.html"
* parameters: an array of parameter to send to the game server.
** Note that "lock: true" must always be specified in this list of parameters in order the interface can be locked during the server call. Cannot use lock: false - to not lock it has to be undefined.
** Note: Restricted parameter names (please don't use them):
*** "action"
*** "module"
*** "class"
* obj_callback: must be set to "this".
* callback (non-optional but rarely used): a function to trigger when the server returns result and everything went fine (not used, as all data handling is done via notifications).
* callback_anycase: (optional) a function to trigger when the server returns ok OR error. If no error this function is called with parameter value false. If an error occurred, the first parameter will be set to true, the second will contain the error message sent by the PHP back-end, and the third will contain an error code.
* ajax_method: (optional and rarely used) if you need to send large amounts of data (over 2048 bytes), you can set this parameter to 'post' (all lower-case) to send a POST request as opposed to the default GET. This works, but was not officially documented, so only use if you really need to.

Usage:
<pre>
this.ajaxcall( '/mygame/mygame/actMyAction.html', { lock: true,
arg1: myarg1,
arg2: myarg2
}, this, (result)=>{} );
</pre>

'''this.checkAction(action: string, nomessage?: boolean): boolean '''

Check if player can do the specified action by taking into account:
* if interface is locked it will return false and show message "An action is already in progress", unless nomessage set to true
* if player is not active it will return false and show message "This is not your turn", unless nomessage set to true
* if action is not in list in possible actions (defined by "possibleaction" in current game state) it will return false and show "This move is not authorized now" error (unconditionally).
* otherwise returns true
Example:
<pre>
function onClickOnGameElement( evt ) {
if( this.checkAction( "actMyAction" ) ) {
// Do the action
}
}
</pre>

'''this.checkPossibleActions(action: string): boolean'''

* this is independent of the player being active, so can be used instead of this.checkAction(). This is particularly useful for multiplayer states when the player is not active in a 'player may like to change their mind' scenario. Unlike this.checkAction, this function does NOT take interface locking into account

* if action is not in list in possible actions (defined by "possibleaction" in current game state) it will return false and show "This move is not authorized now" error (unconditionally).
* otherwise returns true

function onChangeMyMind( evt ) {
if( this.checkPossibleActions( "actMyAction" ) ) {
// Do the action
}
}

'''this.checkLock(nomessage?: boolean): boolean'''

When using "lock: true" in ajax call you can use this function to check if interface is in lock state (it will be locked during server call and notification processing).
This check can be used to block some other interactions which do not result in ajaxcall or if you want to suppress errors. Note: normally you only need to use this.checkAction(...), this is for advanced cases.

It will also show error unless nomessage is set to true

function onChangeMyMind( evt ) {
if( this.checkLock() ) {
// Do the action
}
}

== Notifications ==

When something happens on the server side, your game interface Javascript logic received a notification.
If you have not done so yet check what notification are in [[Main_game_logic:_yourgamename.game.php#Notifications]]

Here's how you can handle these notifications on the client side.

=== Subscribe to notifications ===

'''dojo.subscribe(notif_type: string, callback_obj: Object, handler: string|handler)'''
* notif_type - notification type/name send by php server
* callback_obj - usually this
* handler - if string method of callback_obj with name name is called, when notification is called, with notification object as parameter (see below)

Your Javascript "setupNotifications" method is the place where you can subscribe to notifications from your PHP code.

Here's how you associate one of your Javascript method to a notification "playDisc" (from Reversi example):

<pre>
setupNotifications: function() {
...
dojo.subscribe('playDisc', this, "notif_playDisc");
},
</pre>

Note: the "playDisc" corresponds to the name of the notification you define it in your PHP code, in your "notifyAllPlayers" or "notifyPlayer" method.

Then, you have to define your "notif_playDisc" method:

<pre>
notif_playDisc: function(notif) {
// Remove current possible moves (makes the board more clear)
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );
this.addDiscOnBoard( notif.args.x, notif.args.y, notif.args.player_id );
},
</pre>

In a notification handler like our "notif_playDisc" method, you can access all notifications arguments with "notif.args".

Example:

PHP

<pre>
$this->notifyAllPlayers( "apples", clienttranslate('player takes ${count} apples'), [ "count" => 3 ] );
</pre>

JavaScript

<pre>
setupNotifications: function() {
dojo.subscribe( 'apples', this, 'notif_apples' );
},

notif_apples: function(notif) {
//You can access the "count" like this:
alert("count = " + notif.args.count);
}
</pre>

=== The notification Object received by client ===

When sending a notification on your PHP, the client side will receive an Object with the following attributes:

* type - type of the notification (as passed by php function)
* log - the log string passed from php notification
* args - This is the arguments that you passed on your notification method on php
* bIsTableMsg - is true when you use [[Main_game_logic:_yourgamename.game.php#NotifyAllPlayers|NotifyAllPlayers]] method (false otherwise)
* channelorig - information about table ID (formatted as : "/table/t[TABLE_NUMBER]")
* gamenameorig - name of the game
* move_id - ID of the move associated with the notification
* table_id - ID of the table (comes as string)
* time - UNIX GMT timestamp
* uid - unique identifier of the notification
* h - unknown

'' Note that those information were inferred from observation on console log. If an Admin can confirm/correct (and remove this line), you're welcome :)''

=== Ignoring notifications ===

Sometimes you need to ignore some notification on client side. You don't want them to be shown in game log and you don't want them to be handled.

The most common use case is when a player gets private information. They will receive a specific notification (such as "You received Ace of Heart"), while other players would receive more generic notification ("Player received a card").

In X.game.php
<pre>
$this->notifyAllPlayers("dealCard", clienttranslate('${player_name} received a card'), [
'player_id' => $playerId,
'player_name' => $this->getActivePlayerName()
]);

$this->notifyPlayer($playerId, "dealCardPrivate", clienttranslate('You received ${cardName}'), [
"type" => $card["type"],
"cardName" => $this->getCardName($card["type"])
]);
</pre>

The problem with this approach is that the active player will receive two notifications:
* Player1 received a card
* You received Ace of Hearts

Hence, notification ignoring.

NOTE: You can think that it would be possible to send such notification to all players except active just by using notifyPlayer and it seems to work. The problem however is that table spectators would miss such notification and their user interface (and game log) wouldn't be updated. Since there is no way to send notification just to spectators, ignoring the notification (or "filtering") is the only reasonable solution.

'''setIgnoreNotificationCheck(notif_type: string, predicate: ((notif: Notif)=>boolean))'''

This method will set a check whether any of notifications of specific type should be ignored.

The parameters are:
* notif_type: type of the notification
* predicate (notif => boolean): a function that will receive notif object and will return true if this specific notification should be ignored

Before dispatching any notification of this type, the framework will call predicate to check whether notification should be ignored, if it return true - the notification will be dispatched, i.e. logged or handled.

<pre>
this.notifqueue.setIgnoreNotificationCheck( 'dealCard', (notif) => (notif.args.player_id == this.player_id) );
</pre>

IMPORTANT: Remember that this notification is ignored on the client side, but was still received by the client. Therefore it shouldn't contain any private information as cheaters can get it. In other words this is not a way to hide information.

IMPORTANT: When a game is reloaded with F5 or when opening a turn based game, old notifications are replayed as history notification. They are used just to update the game log and are stripped of all arguments except player_id, i18n and any argument present in message. If you use and other argument in your predicate you should '''preserve''' it as explained [[Main_game_logic:_yourgamename.game.php#Notify_players|here]].

=== Synchronous notifications ===

When several notifications are received by your game interface, these notifications are processed immediately, one after the other, in the same exact order they have been generated in your PHP game logic.

However, sometimes, you need to give some time to the players to figure out what happened on the game before jumping to the next notification. Indeed, in many games, there are a lot of automatic actions, and the computer is going to resolve all these actions very fast if you don't tell it not to do so.

As an example, for Reversi, when someone is playing a disc, we want to wait 500 milliseconds before doing anything else in order the opponent player can figure out what move has been played.

Here's how we do this, right after our subscription:
<pre>
dojo.subscribe( 'playDisc', this, "notif_playDisc" );
this.notifqueue.setSynchronous( 'playDisc', 500 ); // Wait 500 milliseconds after executing the playDisc handler
</pre>

-----

It is also possible to control the delay timing dynamically (e.g., using notification args). As an example, maybe your notification 'cardPlayed' should pause for a different amount of time depending on the number or type of cards played.

For this case, use '''setSynchronous''' without specifying the duration and use '''setSynchronousDuration''' within the notification callback.

* NOTE: If you forget to invoke '''setSynchronousDuration''', the game will remain paused forever!

<pre>
setupNotifications: function () {
dojo.subscribe( 'cardPlayed', this, 'notif_cardPlayed' );
this.notifqueue.setSynchronous( 'cardPlayed' ); // wait time is dynamic
...
},

notif_cardPlayed: function (notif) {
// MUST call setSynchronousDuration

// Example 1: From notification args (PHP)
this.notifqueue.setSynchronousDuration(notif.args.duration);
...

// Or, example 2: Match the duration to a Dojo animation
var anim = dojo.fx.combine([
...
]);
anim.play();
this.notifqueue.setSynchronousDuration(anim.duration);
},
</pre>

You can also manually call this.notifqueue.setSynchronousDuration(0) once client operations are finished, but be careful that even fast replay still has a path to call it.

'''WARNING: combining synchronous and ignored notifications'''
You must be careful when combining dynamic synchronous durations (as described above) with ignored notifications. If you have a conditionally ignored notification like this (see below section):

<pre>this.notifqueue.setIgnoreNotificationCheck( 'myNotif', (notif) => (notif.args.player_id == this.player_id) /* or any other condition */ )</pre>

then you CANNOT do

<pre>this.notifqueue.setSynchronous('myNotif');</pre>

as, when the ignored check passes, the notification handler, in which `this.notifqueue.setSychronousDuration` is called, is never called and so the duration is never set and interface locking results.

The workaround is to set a "dummy" time:

<pre>this.notifqueue.setSynchronous('myNotif', 5000);</pre>

whose value is irrelevant but must be large enough to cover the time before the notification handler is called. The large value never actually comes into play because the notification is either ignored, or the synchronous duration is reset to a sensible value inside the handler.

=== Pre-defined notification types ===

'''tableWindow''' - This defines notification to display [[Game_interface_logic:_yourgamename.js#Scoring_dialogs|Scoring Dialogs]], see below.

'''message''' - This defines notification that shows on players log and have no other effect (technically any unhandled notification will do the same but its recommended to use this keyword for consistency)

// You can call this on php side without doing anything on client side
self::notifyAllPlayers( 'message', clienttranslate('hello'), [] );

'''simplePause''' - This notification will just delay other notifications, maybe useful if you know you need some extra time for animation or something. Requires a time parameter.

<pre>
self::notifyAllPlayers( 'simplePause', '', [ 'time' => 500] ); // time is in milliseconds
</pre>

Note: the following types are RESERVED by framework, do not use:

gameStateChange gameStateChangePrivateArg gameStateMultipleActiveUpdate newActivePlayer playerstatus yourturnack clockalert tableInfosChanged playerEliminated tableDecision archivewaitingdelay end_archivewaitingdelay replaywaitingdelay end_replaywaitingdelay replayinitialwaitingdelay end_replayinitialwaitingdelay aiPlayerWaitingDelay replay_has_ended updateSpectatorList wouldlikethink updateReflexionTime undoRestorePoint resetInterfaceWithAllDatas zombieModeFail zombieModeFailWarning aiError skipTurnOfPlayer zombieBack allPlayersAreZombie gameResultNeutralized playerConcedeGame showTutorial showCursor showCursorClick skipTurnOfPlayerWarning banFromTable resultsAvailable switchToTurnbased newPrivateState infomsg

== Tooltips ==

=== Adding static tooltips ===

'''this.addTooltip(nodeId: string, helpStringTranslated: string, actionStringTranslated: string, delay?: number): void'''

Add a simple text tooltip to the DOM node.

Specify 'helpStringTranslated' to display some information about "what is this game element?".
Specify 'actionStringTranslated' to display some information about "what happens when I click on this element?".

You must specify both of the strings. You can only use one and specify an empty string ('') for the other one.

When you pass text directly function _() must be used for the text to be marked for translation! Except for empty string.

Parameter "delay" is optional. It is primarily used to specify a zero delay for some game element when the tooltip gives really important information for the game - but remember: no essential information must be placed in tooltips as they won't be displayed in some browsers (see [[BGA_Studio_Guidelines|Guidelines]]).

Example:
<pre>
this.addTooltip( 'cardcount', _('Number of cards in hand'), '' );
</pre>

Note: this generates static tooltip and attaches to existing dom element, if you need to generate tooltip more dynamically you have to call that method every time information about object is updated or use completely different tehnique, see dynamic tooltips below.

'''this.addTooltipHtml(nodeId: string, html: string, delay?: number): void'''

Add an HTML tooltip to the DOM node (for more elaborate content such as presenting a bigger version of a card).

'''this.addTooltipToClass(cssClass: string, helpStringTranslated: string, actionStringTranslated: string, delay?: number ): void'''

Add a simple text tooltip to all the DOM nodes set with this cssClass. See more details above for this.addTooltip.
this.addTooltipToClass( 'meeple', _('This is A Meeple'), _('Click to tickle') );

IMPORTANT: all concerned nodes must exist and have IDs to get tooltips.

'''this.addTooltipHtmlToClass(cssClass: string, html: string, delay?: number): void'''

Add an HTML tooltip to to all the DOM nodes set with this cssClass (for more elaborate content such as presenting a bigger version of a card).

IMPORTANT: all concerned nodes must exist and have IDs to get tooltips.

=== Removing static tooltips ===

'''this.removeTooltip(nodeId: string): void'''

Remove a tooltip from the DOM node with given id.

=== Advanced tooltips ===

'''force tooltip to open'''

If you want to force tooltip to open in reaction to some other action, i.e. click you can do this

this.tooltips[id].open(id)

where id is the id of the tooltip node where tooltip was installed.

'''dynamic tooltips'''

See [[BGA_Studio_Cookbook#Dynamic_tooltips]]

'''tooltips on mobile'''

Tooltips is very unreliable on mobile, it is recommended to implement some other method to obtaining same information,
such as simple click handler in dedicated "Help" mode or provide dedicated clickable areas such as corner of card.

== Warning messages ==

Sometimes, there is something important that is happening in the game and you have to make sure all players get the message. Most of the time, the evolution of the game situation or the game log is enough, but sometimes you need something more visible.

Ex: someone fulfills one of the end of the game conditions, so this is the last turn.

'''this.showMessage(msg: string, type: string): void'''

showMessage shows a message in a big rectangular area on the top of the screen of the current player, and it dissapears after few seconds (also it will be in the log in some cases).

* "msg" is the string to display. It should be translated.
* "type" can be set to "info", "error", "only_to_log" or custom string. If set to "info", the message will be an informative message on a white background. If set to "error", the message will be an error message on a red background and it will be added to log. If set to "only_to_log", the message will be added to the game log but will not popup at the top of the screen.
If set to custom string, it will be transparent, to use custom type define "head_xxx" in css, where xxx is the type. For example if you want yellow warning, use "warning" as type and add this to css:
.head_warning {
background-color: #e6c66e;
}

Important: the normal way to inform players about the progression of the game is the game log. The "showMessage" is intrusive and should not be used often.

<pre>
notif_messageinfo: function(notif) {
if (!g_archive_mode) {
var message = this.format_string_recursive(notif.log, notif.args);
this.showMessage(_('Announcement:') + " " + message, 'info');
}
},
</pre>

Show message could be used on the client side to prevent user wrong moves before it is send to server.
Example from 'battleship':
<pre>
onGrid: function(event) {
if (checkIfPlayerTriesToFireOnThemselves(event)) {
this.showMessage(_('This is your own board silly!'), 'error');
return;
}
...
},
</pre>

'''this.showMoveUnauthorized(): void'''

Shows predefined user error that move is unauthorized now

<pre>
onPet: function(event) {
if (checkPet(event)==false) {
this.showMoveUnauthorized();
return;
}
...
},
</pre>

== Dialogs ==

=== Confirmation dialog ===

When an important action with a lot of consequences is triggered by the player, you may want to propose a confirmation dialog.

CAREFUL: the general guideline of BGA is to AVOID the use of confirmation dialogs. Confirmation dialogs slow down the game and bother players. The players know that they have to pay attention to each move when they are playing online.

The situations where you should use a confirmation dialog are the following:
* It must not happen very often during a game.
* It must be linked to an action that can really "kill a game" if the player does not pay attention.
* It must be something that can be done by mistake (ex: a link on the action status bar).

'''this.confirmationDialog(message: string, yesHandler: (param: any) => void, noHandler?: (param: any) => void, param?: any): void'''

* message - message will be shown to user, use _() to translate
* yesHandler - non-optional handler to be called on yes
* noHandler - optional handler to called on no
* param - if specified, it will be passed to both handlers
NOTE: this is async function, it does not return anything and you should not do anything after, you must do everything in handlers

How to display a confirmation dialog:
<pre>
this.confirmationDialog(_("Are you sure you want to bake a pie?"), () => {
this.bakeThePie();
});
return; // nothing should be called or done after calling this, all action must be done in the handler
</pre>
With param and both handlers
<pre>
this.confirmationDialog(_("Are you sure you want to bake a pie?"),
(ingredient) => this.bakeThePie(ingredient),
(ingredient) => console.log(`cancelled baking of ${ingredient}`),
'apple');
</pre>

=== Multiple choice dialog ===

You can use this dialog to give user a choice with small amount of options

'''this.multipleChoiceDialog(message: string, choices: string[], callback: (choice: number) => void): void'''
* message - message will be shown to user, use _() to translate
* choices - array of choices
* callback - non-optional handler to be called on choice made, the choice parameter is the INDEX of the choice from the array of choices

NOTE: this is async function, it does not return anything and you should not do anything after, you must do everything in handlers
NOTE: there is no cancel handler, so make sure you gave user a choice to get out of it

Example:
<pre>
const keys = ["0", "1", "5", "10"];
this.multipleChoiceDialog(_("How many bugs to fix?"), keys, (choice) => {
if (choice==0) return; // cancel operation, do not call server action
var bugchoice = keys[choice]; // choice will be 0,1,2,3 here
this.bgaPerformAction("fixBugs", { number: bugchoice });
});
return; // must return here
</pre>

=== Generic Dialogs ===

As a general rule, you shouldn't use dialogs windows.

BGA guidelines specify that all game elements should be displayed on the main screen. Players can eventually scroll down to see game elements they don't need to see anytime, and you may eventually create anchors to move between game area section. Of course dialogs windows are very practical, but the thing is: all players know how to scroll down, and not all players know how to show up your dialog window. In addition, when the dialog shows up, players can't access the other game components.

Sometimes although, you need to display a dialog window. Here is how you do this:

// Create the new dialog over the play zone. You should store the handler in a member variable to access it later
this.myDlg = new ebg.popindialog();
this.myDlg.create( 'myDialogUniqueId' );
this.myDlg.setTitle( _("my dialog title to translate") );
this.myDlg.setMaxWidth( 500 ); // Optional

// Create the HTML of my dialog.
// The best practice here is to use [[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl#Javascript_templates|Javascript templates]]
var html = this.format_block( 'jstpl_myDialogTemplate', {
arg1: myArg1,
arg2: myArg2,
...
} );

// Show the dialog
this.myDlg.setContent( html ); // Must be set before calling show() so that the size of the content is defined before positioning the dialog
this.myDlg.show();

// Now that the dialog has been displayed, you can connect your method to some dialog elements
// Example, if you have an "OK" button in the HTML of your dialog:
dojo.connect($('my_ok_button'), 'onclick', this, (event) => {
event.preventDefault();
this.myDlg.destroy();
});

If necessary, you can remove the default top right corner 'close' icon, or replace the function called when it is clicked:
// Removes the default close icon
this.myDlg.hideCloseIcon();

// Replace the function call when it's clicked
this.myDlg.replaceCloseCallback((event) => { ... });

=== Scoring dialogs ===

Sometimes at the end of a round you want to display a big table that details the points wins in each section of the game.

Example: in Hearts game, we display at the end of each round the number of "heart" cards collected by each player, the player who collected the Queen of Spades, and the total number of points loose by each player.

Scoring dialogs are managed entirely on '''PHP side''', but they are described here as their effects are visible only on client side.

Displaying a scoring dialog is quite simple and is using a special notification type: "tableWindow":
<pre>
// on PHP side:
$this->notifyAllPlayers( "tableWindow", '', array(
"id" => 'finalScoring',
"title" => clienttranslate("Title of the scoring dialog"),
"table" => $table
));
</pre>

The "table" argument is a 2 dimensional PHP array that describes the table you want to display, line by line and column by column.

Example: display an 3x3 array of strings
<pre>
$table = [
[ "one", "two", "three" ], // This is my first line
[ "four", "five", "six" ], // This is my second line
[ "seven", "height", "nine" ] // This is my third line
];
</pre>

As you can see above, in each "cell" of your array you can display a simple string value. But you can also display a complex value with a template and associated arguments like this:
<pre>
$table = [
[ "one", "two", [ "str" => clienttranslate("a string with an ${argument}"), "args" => [ 'argument' => 'argument_value' ] ] ],
[ "four", "five", "six" ],
[ "seven", "height", "nine" ]
];
</pre>

This is especially useful when you want to display player names with colors. Example from "Hearts":
<pre>
$firstRow = [ '' ];
foreach( $players as $player_id => $player ) {
$cell = [ 'str' => '${player_name}',
'args' => [ 'player_name' => $player['player_name'] ],
'type' => 'header'
];
$firstRow[] = $cell;
}
$table[] = $firstRow;
...
</pre>

You can also use three extra attributes in the parameter array for the notification:
* '''header''': the content for this parameter displays before the table (also, the html will be parsed and player names will be colored according to the current game colors).
* '''footer''': the content for this parameter displays after the table (no parsing for coloring the player names)
* '''closing''': if this parameter is used, a button will be displayed with this label at the bottom of the popup and will allow players to close it (more easily than by clicking the top right 'cross' icon).

<pre>
$this->notifyAllPlayers( "tableWindow", '', [
"id" => 'finalScoring',
"title" => clienttranslate("Title of the scoring dialog"),
"table" => $table,
"header" => ['str' => clienttranslate('Table header with parameter ${number}'),
'args' => [ 'number' => 3 ],
],
"footer" => '<div class="myfoot"></div>',
"closing" => clienttranslate( "Closing button label" )
] );
</pre>

Note: currently id is not used - so you cannot access resulting div by id on js side

Note: any traslatable string have to be wrapped by clienttranslate() on top level OR it has to be recursive template.

DO NOT DO THIS:
<pre>
"footer" => '<div>'.clienttranslate( "The end" ).'</div>', // this will not work for translations!!!
</pre>

=== Scoring animated display ===

Sometimes, you may want to display a score value over an element to make the scoring easier to follow for the players (Terra Mystica final scoring for example).
You can do it with:

'''this.displayScoring(anchor_id: string, color: string, score: number | string, duration?: number, offset_x?: number, offset_y?: number): void'''

'''anchor_id''': ID of the html element to place the animated score onto (without the '#')

'''color''': hexadecimal RGB representation of the color (should be the color of the scoring player), but without a leading '#'. For instance, 'ff0000' for red.

'''score''': numeric score to display, prefixed by a '+' or '-'

'''duration''': animation duration in milliseconds (optional, default is 1000)

'''offset_x''' and '''offset_y''': if both offset_x and offset_y are defined and not null, apply the following offset (in pixels) to the scoring animation.
Note that the score is centered in the anchor, so the offsets might have to be negative if you calculate the position.

Note: if you want to display successively each score, you can use ''this.notifqueue.setSynchronous()'' function.
<pre>
setupNotifications: function() {
dojo.subscribe( 'displayScoring', this, "notif_displayScoring" );
...
}
...

notif_displayScoring: function(notif) {
const duration = notif.args.duration?notif.args.duration:1000;
this.notifqueue.setSynchronous('displayScoring', duration );
this.displayScoring( notif.args.target, notif.args.color, notif.args.score, duration);
},
</pre>

=== Speech bubble ===

For better interactivity in some games (Love Letter for example), you may use comic book style speech bubbles to express the players voices.
This is done with showBubble:

'''this.showBubble(anchor_id: string, text: string, delay?: number, duration?: number, custom_class?: string): void'''

* anchor_id - where to attach the bubble
* text - what to put in bubble, can be html
* delay - delay in milliseconds (optional, default 0)
* duration - duration of animation in milliseconds (optional, default 3000)
* custom_class - extra class to add to bubble (optional), if you need to override the default bubble style

<pre>
this.showBubble('meeple_2', _('Hello'), 0, 1000, 'pink_bubble');
</pre>

<pre>
notif_speechBubble(notif) {
var html = this.format_string_recursive(notif.args.text, notif.args.args);
this.showBubble(notif.args.target, html, notif.args.delay ?? 0, notif.args.duration ?? 1000);
},
</pre>

'''Warning''': if your bubble could overlap other active elements of the interface (buttons in particular), as it stays in place even after disappearing, you should use a custom class to give it the style "pointer-events: none;" in order to intercept click events.

Note: If you want this visually, but want to take complete control over this bubble and its animation (for example to make it permanent) you can just use div with 'discussion_bubble' class on it, and content of div is what will be shown.

== Translations ==

See [[Translations]]

== Players panels ==

=== Update players score ===

The column player_score from the player table is automatically loaded into this.scoreCtrl and therefore into the stars location on the player board. This occurs sometime after the game setup() function. However this score must be updated as the game progresses using notifications.

Note: this.scoreCtrl[player_id] is object of class [[Counter]], you can use other counter API.

Increase a player score (with a positive or negative number):

<pre>
this.scoreCtrl[ player_id ].incValue( score_delta );
</pre>

Set a player score to a specific value:

<pre>
this.scoreCtrl[ player_id ].setValue( new_score );
</pre>

Set a player score to a specific value with animation:

<pre>
this.scoreCtrl[ player_id ].toValue( new_score );
</pre>

Typical usage would be (that will process 'score' notification):
<pre>
setupNotifications : function() {
...
dojo.subscribe('score', this, "notif_score");
},
notif_score: function(notif) {
this.scoreCtrl[notif.args.player_id].setValue(notif.args.player_score);
},
</pre>

=== Adding stuff to player's panel ===

At first, create a new "JS template" string in your template (tpl) file:

(from Gomoku example)
<pre>
var jstpl_player_board = '\<div class="cp_board">\
<div id="stoneicon_p${id}" class="gmk_stoneicon gmk_stoneicon_${color}"></div><span id="stonecount_p${id}">0</span>\
</div>';
</pre>

Then, you add this piece of code in your JS file to add this template to each player panel:

<pre>
// Setting up player boards
for( var player_id in gamedatas.players )
{
var player = gamedatas.players[player_id];

// Setting up players boards if needed
var player_board_div = $('player_board_'+player_id);
dojo.place( this.format_block('jstpl_player_board', player ), player_board_div );
}
</pre>

(Note: the code above is of course from your "setup" function in your Javascript).

Very often, you have to distinguish current player and others players. In this case, you just have to create another JS template (ex: jstpl_otherplayer_board) and use it when "player_id" is different than "this.player_id".

=== Fixing Player Panel heights ===

You may find that the player panels don't automatically resize when adding something to (or removing something from) a player panel while the display is in portrait mode (i.e. the player summary panels are at the top of the screen rather than down the right side).

When this happens, call <pre>this.adaptPlayersPanels();</pre> This recalculates the layout and also adjusts the position of the actionbar for you.

=== Player's panel disabling/enabling ===

'''this.disablePlayerPanel(player_id: number): void'''

Disable given player panel (the panel background become gray).

Usually, this is used to signal that this played passes, or will be inactive during a while.

Note that the only effect of this is visual. There are no consequences on the behaviour of the panel itself.

'''this.enablePlayerPanel(player_id:number): void'''

Enable a player panel that has been disabled before.

'''this.enableAllPlayerPanels(): void'''

Enable all player panels that has been disabled before.

=== Player order ===

'''this.updatePlayerOrdering(): void'''

This function makes sure that player order in player's panel matches this.gamedatas.playerorder and its normally called by framework.
You can call it yoursel if you change this.gamedatas.playerorder from notification.
Also you can override this function to change defaults OR insert a non-player panel [[BGA_Studio_Cookbook#Inserting_non-player_panel]].

=== Counters ===
Note: there is bga component called "ebg/counter" this API is not using it, these methods
below declared right in core game. If you need animation for counters use ebg/counter

To use this API just create a counter dom element like this (class does not really matter)
<pre>
<div class="counter" id="bread"></div>
<div class="counter" id="coin"></div>
</pre>
The "bread" will the counter name.

The php code should send all "counters" data from getAllDatas() method like this

game.php
<pre>
protected function getAllDatas() {
// (the key must match counter_name)
$result['counters']=[
'bread' => [
'counter_name' => 'bread',
'counter_value' => 3
],
'coin' => [
'counter_name' => 'coin',
'counter_value' => 5
]
];
return $result;
}
</pre>

'''setCounter(counter_name: stirng, new_value: string | number): void'''

updates the global this.gamedatas.counters and value of node $(counter_name)
<pre>
notif_counter: function(notif) {
this.setCounter(notif.args.counter_name, notif.args.counter_value);
},
</pre>

'''incCounter(counter_name: string, delta: number): void'''
<pre>
notif_counter : function(notif) {
this.incCounter(notif.args.counter_name, notif.args.inc);
},
</pre>

'''updateCounters(counters: object): void'''

Useful for updating game counters in the player panel (such as resources).
'counters' arg is map of counters (the key must match counter_name)
{
'bread': {
'counter_name' : 'bread',
'counter_value' => 3
},
'coin': {
'counter_name' : 'coin',
'counter_value' => 5
}
}
All counters MUST be referenced in this.gamedatas.counters (means they should be send from php) and will be updated.
DOM objects referenced by 'counter_name' will have their innerHTML updated with 'counter_value'.

Usually you call this from notification

<pre>
notif_counter : function(notif) {
this.updateCounters(notif.args.counters);
},
</pre>

== BGA GUI components ==

BGA framework provides some useful ready-to-use components for the game interface:

[[Studio#BGA_Studio_game_components_reference]]

Note that each time you are using an additional component, you must declare it at the top of your Javascript file in the list of modules used.

Example if you are using "ebg.stock":
<pre>
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/stock" /// <=== we are using ebg.stock module
],
</pre>

== BGA Buttons ==

=== Basic Button ===

'''this.addActionButton(id: string, label: string, method: string | eventhandler, destination?: string, blinking?: boolean, color?: string): void'''

You can use this method to add an action button in the main action status bar (or other places).

Arguments:
* id: an element ID that should be unique in your HTML DOM document.
* label: the text of the button. Should be translatable (use _() function). Note: this can also be any html, such as "<div class='brick'></div>", see example below on how to make image action buttons.
* method: the name of your method that must be triggered when the player clicks on this button (can be name of the method on game class or handler).
* destination (optional): id of parent on where to add button, ONLY use in rare cases if location is not action bar. Use '''null''' as value if you need to specify other arguments.
* blinking (optional): if set to '''true''', the button is going blink to catch player's attention. Please DO NOT abuse blinking button. If you need button to blink after some time passed add class 'blinking' to the button later.
* color: could be '''blue''' (default), '''red''','''gray''' or '''none'''.

You should only use this method in your "onUpdateActionButtons" method. Usually, you use it like this:

<pre>
onUpdateActionButtons: function( stateName, args ) {
if (this.isCurrentPlayerActive()) {
switch( stateName ) {
case 'giveCards':
this.addActionButton( 'giveCards_button', _('Give selected cards'), 'onGiveCards' );
this.addActionButton( 'pass_button', _('Pass'), () => this.bgaPerformAction('actPass') );
break;
}
}
},
</pre>

In the example above, we are adding a "Give selected cards" button in the case we are on game state "giveCards". When player clicks on this button, it triggers our "onGiveCards" method.

Example using blinking red button:
<pre>
this.addActionButton( 'button_confirm', _('Confirm?'), 'onConfirm', null, true, 'red');
</pre>

If you want to call the handler with arguments, you can use arrow functions, like this:
<pre>
this.addActionButton( 'commit_button', _('Confirm'), () => this.onConfirm(this.selectedCardId), null, false, 'red');
</pre>

=== Image Button ===

You can use the same method, but add extra class to a button to disable the padding and style it, i.e.
<pre>
this.addActionButton( 'button_brick', '<div class="brick"></div>', ()=>{... on brick ...}, null, null, 'gray');
dojo.addClass('button_brick','bgaimagebutton');
</pre>

where

<pre>
.bgaimagebutton {
padding: 0px 12px;
min-height: 28px;
border: none;
}
</pre>

If you use this a lot, you can define a helper function, i.e.
<pre>
/**
* This method can be used instead of addActionButton, to add a button which is an image (i.e. resource). Can be useful when player
* need to make a choice of resources or tokens.
*/
addImageActionButton: function(id, div, handler, bcolor, tooltip) {
if (typeof bcolor == "undefined") {
bcolor = "gray";
}
// this will actually make a transparent button id color = gray
this.addActionButton(id, div, handler, null, false, bcolor);
// remove border, for images it better without
dojo.style(id, "border", "none");
// but add shadow style (box-shadow, see css)
dojo.addClass(id, "shadow bgaimagebutton");
// you can also add additional styles, such as background
if (tooltip) {
dojo.attr(id, "title", tooltip);
}
return $(id);
},
</pre>

=== Disabling Button ===

You can disable the '''bgabutton''' by adding the css class '''disabled''' in you js. The disabled button is still visible but is grey and not clickable.
For example in the '''onUpdateActionButtons''' :
<pre>
this.addActionButton('play_button_id', _('Play 1 to 3 cards'), 'playFunctionButton');
if (condition) {
dojo.addClass('play_button_id', 'disabled');
}
</pre>

=== Custom Buttons ===

You can create a custom button, but the BGA framework provides a standard button that requires only .css classes: '''bgabutton''' and '''bgabutton_${color}'''.

'''Examples:'''

<pre>
<a href="#" id="my_button_id" class="bgabutton bgabutton_blue"><span>My blue button</span></a>

<a href="#" id="my_button_id" class="bgabutton bgabutton_red bgabutton_big"><span>My big red button</span></a>
</pre>

'''Note''': To see it in action, check out ''Coloretto''.

=== Button outside of action bar ===

Use addActionButton() method with destination argument set
<pre>
this.addActionButton( 'commit_button', _('Confirm'), 'onConfirm', 'player_board', true, 'red');
</pre>

in example above the button will be place on object with id 'player_board'

== Image loading ==

See also [[Game_art:_img_directory]].

'''Be careful''': by default, ALL images of your img directory are loaded on a player's browser when he loads the game. For this reason, don't let in your img directory images that are not useful, otherwise it's going to slowdown the game load.

'''this.dontPreloadImage(image_file_name: string)'''

Using dontPreloadImage, you tell the interface to not preload a specific image in your img directory.

Example of use:
<pre>
this.dontPreloadImage( 'cards.png' );
</pre>

This is particularly useful if for example you have 2 different themes for a game. To accelerate the loading of the game, you can specify to not preload images corresponding to the other theme.

Another example of use: in "Gosu" game with Kamakor extension, you play with 5 sets of cards among 10 available. Cards images are organized by sets, and we only preload the images corresponding to the 5 current sets with '''ensureSpecificGameImageLoading( image_file_names_array )'''.
<pre>
// By default, do not preload anything
this.dontPreloadImage( 'cards.png' );
this.dontPreloadImage( 'clan1.png' );
this.dontPreloadImage( 'clan2.png' );
this.dontPreloadImage( 'clan3.png' );
this.dontPreloadImage( 'clan4.png' );
this.dontPreloadImage( 'clan5.png' );
this.dontPreloadImage( 'clan6.png' );
this.dontPreloadImage( 'clan7.png' );
this.dontPreloadImage( 'clan8.png' );
this.dontPreloadImage( 'clan9.png' );
this.dontPreloadImage( 'clan10.png' );
var to_preload = [];
for( i in this.gamedatas.clans )
{
var clan_id = this.gamedatas.clans[i];
to_preload.push( 'clan'+clan_id+'.png' );
}

this.ensureSpecificGameImageLoading( to_preload );

</pre>

'''Note:''' You don't need to specify to not preload game box images (game_box.png, game_box75.png...) since they are not preloaded by default.

'''this.ensureSpecificGameImageLoading(list: string[])'''

This is oppostive of dontPreloadImage - its ensure specific images is loaded. Note: only makes sense if preload list is empty, otherwise everything is loaded anyway

'''load specific images'''
All images that will be preloaded stored in g_img_preload. If you want to override it directly - there is no API, but you can do this in GAME constructor

g_img_preload = ['tokens.png', 'trains.png', 'loc_plan.png', 'eng.png', 'eng-back.png'];

You can also set it to empty array and call ensureSpecificGameImageLoading() on specific images

== Sounds ==

Add a custom sound and make it load with your interface:

Add this in your template (.tpl) file:
<pre>
<audio id="audiosrc_<gamename>_<yoursoundname>" src="{GAMETHEMEURL}img/<gamename>_<yoursoundname>.mp3" preload="none" autobuffer></audio>
<audio id="audiosrc_o_<gamename>_<yoursoundname>" src="{GAMETHEMEURL}img/<gamename>_<yoursoundname>.ogg" preload="none" autobuffer></audio>
</pre>

Note: this is a requirement to provide both a mp3 and a ogg file with the names <code><gamename>_<yoursoundname>[.ogg][.mp3]</code>.

Play the sound (from your .js file):

<pre>
playSound('<gamename>_<yoursoundname>'); // do not add 'this.' - its a global function
</pre>

Disable the standard "move" sound for this move (to replace it with your custom sound):

Add this to your notification handler:

<pre>
this.disableNextMoveSound();
</pre>

Note: it only disable the sound for the next move.

== Title bar and states ==

=== Client states ===

Client states is a way to simulate the state transition but without actually going
to server. It is usefull when you need to ask user multiple questions before you
send things to server

'''this.setClientState(newState: string, args: object)'''

Example:
this.setClientState("client_playerPicksLocation", {
descriptionmyturn : _("${you} must select location"),
});

For more information see [[BGA_Studio_Cookbook#Multi_Step_Interactions:_Select_Worker.2FPlace_Worker_-_Using_Client_States]]

'''this.restoreServerGameState()'''
If you are in client state it will restore the current server state (cheap undo)

'''this.on_client_state'''
Boolean indicating that we are in client state

=== Title bar ===
If you simply want to show something in title bar you can do it directly
$('pagemaintitletext').innerHTML = text;

This however will not work with parameters and will not draw You in color,
if you want to do proper args rendering use method below

;'''this.removeActionButtons()'''
Removes all buttons from title bar

;'''this.updatePageTitle()'''
:This function allows to update the current page title and turn description according to the game state arguments. If the current game state description this.gamedatas.gamestate.descriptionmyturn is modified before calling this function it allows to update the turn description without changing state. This will handle arguments substitutions properly.

Note: this functional also will calls this.onUpdateActionButtons, if you want different buttons then state defaults, use method in example to replace them, if it becomes too clumsy use client states (see above)

Example from Terra Mystica:
<pre>
onClickFavorTile: function( evt ) {
...
if ( ... ) {
this.gamedatas.gamestate.descriptionmyturn = _('Special action: ') + _('Advance 1 space on a Cult track');
this.updatePageTitle();
this.removeActionButtons();
this.addActionButton( ... );
...
return;
}
...

}
</pre>

== User preferences ==
'''this.getGameUserPreference(pref_id)'''

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

'''this.setGameUserPreference(pref_id, value)'''

Programmatically change a user preference. It will have the same effect as if the player changed the value in the select combo box, in the top-right menu.

'''this.onGameUserPreferenceChanged'''

A callback you can define if you want to be notified when a user changes a user preference.

Example:<pre>
onGameUserPreferenceChanged: function(pref_id, pref_value) {
switch (pref_id) {
case 201:
document.getElementsByTagName('html')[0].classList.toggle('dark-background', pref_value == 2);
break;
}
}
</pre>

== Other useful stuff ==

'''dojo.hitch'''

With dojo.hitch, you can create a callback function that will run with your game object context whatever happen.

Typical example: display a BGA confirmation dialog with a callback function created with dojo.hitch:

<pre>
this.confirmationDialog( _('Are you sure you want to make this?'), dojo.hitch( this, function() {
this.bgaPerformAction('makeThis');
} ) );
</pre>

In the example above, using dojo.hitch, we ensure that the "this" object will be set when the callback is called.

NOTE: In modern JS there are lambdas that eliminate need for that, the example above will look like this
<pre>
this.confirmationDialog( _('Are you sure you want to make this?'), () => this.bgaPerformAction( 'makeThis') );
</pre>

;'''onScreenWidthChange()'''
:This function can be overridden in your game to manage some resizing on the client side when the browser window is resized. This function is also triggered at load time, so it can be used to adapt to the :viewport size at the start of the game too.

; this.bRealtime
: Return true if the game is in realtime. Note that having a distinct behavior in realtime and turn-based should be exceptional.

; g_replayFrom
: Global contains replay number in live game, it is set to undefined (i.e. not set) when it is not a replay mode, so consequentially the good check is '''typeof g_replayFrom != 'undefined'''' which returns true if the game is in replay mode <i>during the game</i> (the game is ongoing but the user clicked "replay from this move" in the log)

; g_archive_mode
: Returns true if the game is in archive mode <i>after the game</i> (the game has ended)

; this.instantaneousMode
: Returns true during replay/archive mode if animations should be skipped. Only needed if you are doing custom animations. (The BGA-provided animation functions like <i>this.slideToObject()</i> automatically handle instantaneous mode.)
: Technically, when you click "replay from move #20", the system replays the game from the very beginning with moves 0 - 19 happening in instantaneous mode and moves 20+ happening in normal mode.

; g_tutorialwritten
: Returns an object like the below if the game is in tutorial mode, or undefined otherwise. Tutorial mode is a special case of archive mode where comments have been added to a previous game to teach new players the rules.
{
author: "91577332",
id: "576",
mode: "view"
status: "alpha"
version_override: null
viewer_id: "84554161"
}

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

[[Category:Studio]]

Game interface logic: Game.js

2024-09-25T18:10:32Z

Sguzzer Gunayer: /* Ignoring notifications */

{{Studio_Framework_Navigation}}

__TOC__

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

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

== File structure ==

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

Here is the basic structure:

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

More details:

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

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

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

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

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

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

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

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

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

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

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

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

== Dojo framework ==

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

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

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

== Javascript minimization (after July 2020) ==

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

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

== Accessing Players Information ==

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

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

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

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

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

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

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

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

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

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

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

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

== Accessing and manipulating the DOM ==

=== Element by Id ===

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

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

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

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

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

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

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

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

=== Style ===

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

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

Examples:

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

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

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

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

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

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

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

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

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

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

=== Classes ===

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

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

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

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

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

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

Example from ''Reversi'':

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

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

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

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

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

'''Vanilla JS classList'''

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

=== Attributes ===

;dojo.attr

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

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

'''Vanilla JS attr'''

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

=== Queries ===

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

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

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

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

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

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

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

'''Vanilla JS query'''

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

=== Creating and Destroying elements ===

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

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

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

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

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

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

Create element

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

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

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

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

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

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

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

const div = ``;
'''this.format_string_recursive'''

This bga function is similar to this.format_string but is capable of processing recursive argument structures and translations. It is used to format server notifications.

TODO: find better place for these function docs

=== Moving elements ===

'''dojo.place(node: string | Element, refNode: ElementOrId, pos?: string | number): Element'''

dojo.place is the best function to insert HTML code somewhere in your game interface without breaking something. It is much better to use than the '''innerHTML=''' method if you must insert HTML tags and not only values.

node: can be a string or a DOM node. If it is a string starting with “<”, it is assumed to be an HTML fragment, which will be created. Otherwise it is assumed to be an id of a DOM node.

<pre>
// Insert your HTML code as a child of a container element
dojo.place( "<div class='foo'></div>", "your_container_element_id" );
</pre>

pos: optional argument. Can be a number or one of the following strings: “before”, “after”, “replace”, “only”, “first”, or “last”. If omitted, “last” is assumed.

* "replace": replace the container element with my_node element
* "first": places the node as a child of the reference node. The node is placed as the first child.
* "last" (default): places the node as a child of the reference node. The node is placed as the last child.
* "before": places the node right before the reference node.
* "after": places the node right after the reference node.
* "only": replaces all children of the reference node with the node.

this parameter can be a positive integer. In this case, the node will be placed as a child of the reference node with this number (counting from 0). If the number is more than number of children, the node will be appended to the reference node making it the last child.

<pre>
// Replace all children of container with my_node
dojo.place( $('my_node'), "your_container_element_id", "only" );
</pre>

See also full doc on dojo.place: [https://dojotoolkit.org/reference-guide/1.7/dojo/place.html]

Usually, when you want to insert some piece of HTML in your game interface, you should use "[[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl#Javascript_templates|Javascript templates]]".

But you can also relocate elements like that. Note: it won't animate if you do that.

'''this.placeOnObject(mobile_obj: ElementOrId, target_obj: ElementOrId): void'''

places mobile_obj on target_obj, set the absolute positions and centers the mobile_obj on target_obj,
effect is immediate

This is not really an animation, but placeOnObject is frequently used before starting an animation.

Example:
<pre>
// (We just created an object "my_new_token")

// Place the new token on current player board
this.placeOnObject( "my_new_token", "overall_player_board_"+this.player_id );

// Then slide it to its position on the board
this.slideToObject( "my_new_token", "a_place_on_board" ).play();
</pre>

'''this.placeOnObjectPos(mobile_obj: ElementOrId, target_obj: ElementOrId, target_x: number, target_y: number): void'''

This method works exactly like placeOnObject, except than you can specify some (x,y) coordinates (in px). This way, the center of "mobile_obj" will be placed to the specified x,y position relatively to the center of "target_obj".

''Note: the placement works differently from this.slideToObjectPos'', since coordinates are calculated based on the center of objects.

'''this.attachToNewParent(mobile_obj: ElementOrId, target_obj: ElementOrId): void'''

With this method, you change the HTML parent of "mobile_obj" element without moving it.
"target_obj" is the new parent of this element. The beauty of
attachToNewParent is that the mobile_obj element DOES NOT MOVE during this process.

What happens is that the method calculate a relative position of mobile_obj to make sure it does not move after the HTML parent changes.

Why using this method?

Changing the HTML parent of an element can be useful for the following reasons:
* When the HTML parent moves, all its child are moving with them. If some game elements is no more linked with a parent HTML object, you may want to attach it to another place.
* The z_order (vertical order of display) depends on the position in the DOM, so you may need to change the parent of some game elements when they are moving in your game area.

'''CAREFUL''': this function destroys original object and places a clone onto a new parent, this will break all references to this HTML element (ex: dojo.connect).
If you need version that does not destroy the object but the same otherwise see [[BGA_Studio_Cookbook#Attach_to_new_parent_without_destroying_the_object]]

== Animations ==

===Dojo Animations===

BGA animations is based on Dojo Animation ([http://dojotoolkit.org/documentation/tutorials/1.8/animation/ see tutorial here]).

However, most of the time, you can just use methods below, which are built on top of Dojo Animation.

Note: one interesting method from Dojo that could be useful from time to time is "Dojo.Animation". It allows you to make any CSS property "slide" from one value to another.

Note 2: the slideTo methods are not compatible with CSS transform (scale, zoom, rotate...). If possible, avoid using CSS transform on nodes that are being slided. Eventually, the only possible solution to make these 2 compatible is to disable all CSS transform properties, use slideToObjectPos/placeOnObjectPos, and then apply them again.

===Sliding===

'''this.slideToObject(mobile_obj: ElementOrId, target_obj: ElementOrId, duration?: number, delay?: number): Animation'''

You can use slideToObject to "slide" an element to a target position.

Sliding element on the game area is the recommended and the most used way to animate your game interface. Using slides allow players to figure out what is happening on the game, as if they were playing with the real boardgame.

The parameters are:
* mobile_obj: the ID of the object to move. This object must be "relative" or "absolute" positioned.
* target_obj: the ID of the target object. This object must be "relative" or "absolute" positioned. Note that it is not mandatory that mobile_obj and target_obj have the same size. If their size are different, the system slides the center of mobile_obj to the center of target_obj.
* duration: (optional) defines the duration in millisecond of the slide. The default is 500 milliseconds.
* delay: (optional). If you defines a delay, the slide will start only after this delay. This is particularly useful when you want to slide several object from the same position to the same position: you can give a 0ms delay to the first object, a 100ms delay to the second one, a 200ms delay to the third one, ... this way they won't be superposed during the slide.

BE CAREFUL: The method returns an dojo.fx animation, so you can combine it with other animation if you want to. It means that you have to call the "play()" method, otherwise the animation WON'T START.

Example:
<pre>
this.slideToObject( "some_token", "some_place_on_board" ).play();
</pre>

'''this.slideToObjectPos(mobile_obj: ElementOrId, target_obj: ElementOrId, target_x: number, target_y: number, duration?: number, delay?: number): Animation'''

This method does exactly the same as "slideToObject", except than you can specify some (x,y) coordinates. This way, "mobile_obj" will slide to the specified x,y position relatively to "target_obj".

Example: slide a token to some place on the board, 10 pixels from the top:
<pre>
this.slideToObjectPos( "some_token", "some_place_on_board", 0, 10 ).play();
</pre>

'''this.slideTemporaryObject(mobile_obj_html: string, parent: ElementOrId, from: ElementOrId, to: ElementOrId, duration?: number, delay?: number): Animation'''

This method is useful when you want to slide a temporary HTML object from one place to another. As this object does not exists before the animation and won't remain after, it could be complex to create this object (with dojo.place), to place it at its origin (with placeOnObject) to slide it (with slideToObject) and to make it disappear at the end.

slideTemporaryObject does all of this for you:
* mobile_obj_html is a piece of HTML code that represent the object to slide.
* parent is the ID of an HTML element of your interface that will be the parent of this temporary HTML object.
* from is the ID of the origin of the slide.
* to is the ID of the target of the slide.
* duration/delay works exactly like in "slideToObject"

Example:
<pre>
this.slideTemporaryObject( '<div class="token_icon"></div>', 'tokens', 'my_origin_div', 'my_target_div' ).play();
</pre>

===Destroy===
'''this.slideToObjectAndDestroy(mobile_obj: ElementOrId, target_obj: ElementOrId, duration?: number, delay?: number): void'''

This method is a handy shortcut to slide an existing HTML object to some place then destroy it upon arrival. It can be used for example to move a victory token or a card from the board to the player panel to show that the player earns it, then destroy it when we don't need to keep it visible on the player panel.

It works the same as this.slideToObject and takes the same arguments, but it starts the animation.

CAREFUL: Make sure nothing is creating the same object at the same time the animation is running, because this will cause some random disappearing effects

Example:
<pre>
this.slideToObjectAndDestroy( "some_token", "some_place_on_board", 1000, 0 );
</pre>

'''this.fadeOutAndDestroy( node: string | Element, duration?: number, delay?: number):''' '''void'''

This function fade out the target node, then destroy it. Its starts the animation.
* duration/delay works exactly like in "slideToObject"

Example:
<pre>
this.fadeOutAndDestroy( "a_card_that_must_disappear" );
</pre>

CAREFUL: the HTML node still exists until during few milliseconds, until the fadeOut has been completed.
Make sure nothing is creating same object at the same time as animation is running, because you will be some random dissapearing effects

===Rotating elements===

This example combines "Dojo.Animation" method and a CSS property transform that allow you to rotate the element.
<pre>
// node is Element we rotating
var animation = new dojo.Animation({
curve: [fromDegree, toDegree],
onAnimate: (v) => {
node.style.transform = 'rotate(' + v + 'deg)';
}
});

animation.play();
</pre>

BGA has its own interface to rotate

'''this.rotateTo(node: string | Element, degree: number): void'''

It starts the animation, and stored the rotation degree in the class, so next time you rotate object - it is additive.
There is no animation hooks in this one, if you need to change any parameters use dojo animation above.

There is also '''rotateInstantTo''' with same signature which does not animate

===Animation Callbacks===

If you wish to run some code only after an animation has completed you can do this by linking a callback method to 'onEnd'.

<pre>
var animation_id = this.slideToObject( mobile_obj, target_obj, 500 );
dojo.connect(animation_id, 'onEnd', () => {
// do something here
});
animation_id.play();
</pre>

If you wish to call a second animation after the first (rather than general code) then you can use a dojo animation chain (see tutorial referenced above).

== Players input ==

=== Connecting ===
'''dojo.connect(element: Element, event: string, context: object, method: eventHandler): any'''

'''dojo.connect(element: Element, event: string, handler: eventHandler): any'''

Used to associate a player event with one of your notification methods.

Example: associate a click on an element ("my_element") with one of our methods ("onClickOnMyElement"):
<pre>
dojo.connect( $('my_element'), 'onclick', this, 'onClickOnMyElement' );
</pre>

Same idea but based on query (i.e. all element of 'pet' class)
dojo.query(".pet").connect('onclick', this, 'onPet');

Note: if you need to disconnect the handler you have to store handler returned from this method, i.e.

<pre>
var handler = dojo.connect(...);
...
dojo.disconnect(handler);
</pre>

If you don't store the handler - you have to destroy the object to disconnect it

Typical function that implements the input handler will look like this

<pre>
onPet: function(event) {
var id = event.currentTarget.id;
console.log('onPet ' + id);
dojo.stopEvent(event);
if (this.gamedatas.gamestate.name == 'playerTurnPet') {
this.bgaPerformAction('actPlayPet', {card: id});
} else {
this.showMoveUnauthorized();
}
}
</pre>

'''this.connect(element: ElementOrId, event: string, method: eventHandler): void'''

Used to associate a player event with one of your notification methods.

this.connect( $('my_element'), 'onclick', 'onClickOnMyElement' );

Or you can use an in-place handler

this.connect( $('my_element'), 'onclick', (e) => { console.log('boo'); } );

Note that this function stores the connection handler. That is the only real difference between '''this.connect''' and '''dojo.connect'''. If you plan to destroy the element you connected, you '''must''' call this.disconnect() to prevent memory leaks.
This function is mainly for permanent objects - if you just want to connect the temp object you should probably not use this method but use dojo.connect which won't require any clean-up.

'''this.connectClass(cssClassName: string, event: string, method: eventHandler): void'''

Same as connect(), but for all the nodes set with the specified cssClassName.
this.connectClass('pet', 'onclick', 'onPet');
'''this.disconnect(element: ElementOrId, event: string): void'''

Disconnect event handler (previously registered with this.connect or this.connectClass).

this.disconnect( $('my_element'), 'onclick');

Note: dynamic connect/disconnect is for advanced cases ONLY, you should always connect elements statically if possible, i.e. in setup() method.

'''this.disconnectAll(): void'''

Disconnect all previously registed event handlers (registered via this.connect or this.connectClass)

this.disconnectAll();

=== Actions ===

'''this.bgaPerformAction(action: string, args?: object, options: object = { lock: true, checkAction: true }): Promise<void>'''

Triggers an action on the backend. This is a combination of checkAction and ajaxcall, returning a Promise which resoves when ajaxcall ends.

This method must be used to send a player input to the game server. '''It should not be triggered programmatically''', especially not in loops, in callbacks, in notifications, or in onEnteringState/onUpdateActionButtons/onLeavingState, in order not to create race conditions or break replay game and tutorial features. It should be used only in reaction to a user action in the interface.

* action: name of the action, as it is written in "possibleactions" of the current state.
* args: an object containing the call parameters to send to the action
* options: options to tweak the call with some defaults. Default is <code>{ lock: true, checkAction: true }</code>.

Example of a standard call without args:
this.bgaPerformAction('pass');

Example of a standard call with action args:
this.bgaPerformAction('actPlayCard', { id: this.selectedCardId });

Example of a call without checking action (because player is inactive in a multiactive state):

this.bgaPerformAction('actChangeMind', {}, { checkAction: false });

Example of a call without lock (because of a special action not directly related to the game flow):

this.bgaPerformAction('actSetAutoBid', { alwaysBidUntil: 500 }, { lock: false, checkAction: false });

Example of call with reaction to exception:
this.bgaPerformAction('actPlayCard', { id: this.selectedCardId }).catch(()=>{ this.selectedCardId = undefined; });

Example of call with reaction to success:
this.bgaPerformAction('actPlayCard', { id: this.selectedCardId }).then(()=>{ this.unselectAll(); });

'''this.ajaxcall(url, parameters, obj_callback, callback, callback_anycase?, ajax_method?: string)'''

''Note: bgaPerformAction is a simpler way to use ajax calls, ajaxcall stays in the doc for legacy reasons only and should not be used in new projects.''

Same warning as '''this.bgaPerformAction''' about using on user action only.

* url: the url of the action to perform. For a game, it must be: "/<mygame>/<mygame>/myAction.html"
* parameters: an array of parameter to send to the game server.
** Note that "lock: true" must always be specified in this list of parameters in order the interface can be locked during the server call. Cannot use lock: false - to not lock it has to be undefined.
** Note: Restricted parameter names (please don't use them):
*** "action"
*** "module"
*** "class"
* obj_callback: must be set to "this".
* callback (non-optional but rarely used): a function to trigger when the server returns result and everything went fine (not used, as all data handling is done via notifications).
* callback_anycase: (optional) a function to trigger when the server returns ok OR error. If no error this function is called with parameter value false. If an error occurred, the first parameter will be set to true, the second will contain the error message sent by the PHP back-end, and the third will contain an error code.
* ajax_method: (optional and rarely used) if you need to send large amounts of data (over 2048 bytes), you can set this parameter to 'post' (all lower-case) to send a POST request as opposed to the default GET. This works, but was not officially documented, so only use if you really need to.

Usage:
<pre>
this.ajaxcall( '/mygame/mygame/actMyAction.html', { lock: true,
arg1: myarg1,
arg2: myarg2
}, this, (result)=>{} );
</pre>

'''this.checkAction(action: string, nomessage?: boolean): boolean '''

Check if player can do the specified action by taking into account:
* if interface is locked it will return false and show message "An action is already in progress", unless nomessage set to true
* if player is not active it will return false and show message "This is not your turn", unless nomessage set to true
* if action is not in list in possible actions (defined by "possibleaction" in current game state) it will return false and show "This move is not authorized now" error (unconditionally).
* otherwise returns true
Example:
<pre>
function onClickOnGameElement( evt ) {
if( this.checkAction( "actMyAction" ) ) {
// Do the action
}
}
</pre>

'''this.checkPossibleActions(action: string): boolean'''

* this is independent of the player being active, so can be used instead of this.checkAction(). This is particularly useful for multiplayer states when the player is not active in a 'player may like to change their mind' scenario. Unlike this.checkAction, this function does NOT take interface locking into account

* if action is not in list in possible actions (defined by "possibleaction" in current game state) it will return false and show "This move is not authorized now" error (unconditionally).
* otherwise returns true

function onChangeMyMind( evt ) {
if( this.checkPossibleActions( "actMyAction" ) ) {
// Do the action
}
}

'''this.checkLock(nomessage?: boolean): boolean'''

When using "lock: true" in ajax call you can use this function to check if interface is in lock state (it will be locked during server call and notification processing).
This check can be used to block some other interactions which do not result in ajaxcall or if you want to suppress errors. Note: normally you only need to use this.checkAction(...), this is for advanced cases.

It will also show error unless nomessage is set to true

function onChangeMyMind( evt ) {
if( this.checkLock() ) {
// Do the action
}
}

== Notifications ==

When something happens on the server side, your game interface Javascript logic received a notification.
If you have not done so yet check what notification are in [[Main_game_logic:_yourgamename.game.php#Notifications]]

Here's how you can handle these notifications on the client side.

=== Subscribe to notifications ===

'''dojo.subscribe(notif_type: string, callback_obj: Object, handler: string|handler)'''
* notif_type - notification type/name send by php server
* callback_obj - usually this
* handler - if string method of callback_obj with name name is called, when notification is called, with notification object as parameter (see below)

Your Javascript "setupNotifications" method is the place where you can subscribe to notifications from your PHP code.

Here's how you associate one of your Javascript method to a notification "playDisc" (from Reversi example):

<pre>
setupNotifications: function() {
...
dojo.subscribe('playDisc', this, "notif_playDisc");
},
</pre>

Note: the "playDisc" corresponds to the name of the notification you define it in your PHP code, in your "notifyAllPlayers" or "notifyPlayer" method.

Then, you have to define your "notif_playDisc" method:

<pre>
notif_playDisc: function(notif) {
// Remove current possible moves (makes the board more clear)
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );
this.addDiscOnBoard( notif.args.x, notif.args.y, notif.args.player_id );
},
</pre>

In a notification handler like our "notif_playDisc" method, you can access all notifications arguments with "notif.args".

Example:

PHP

<pre>
$this->notifyAllPlayers( "apples", clienttranslate('player takes ${count} apples'), [ "count" => 3 ] );
</pre>

JavaScript

<pre>
setupNotifications: function() {
dojo.subscribe( 'apples', this, 'notif_apples' );
},

notif_apples: function(notif) {
//You can access the "count" like this:
alert("count = " + notif.args.count);
}
</pre>

=== The notification Object received by client ===

When sending a notification on your PHP, the client side will receive an Object with the following attributes:

* type - type of the notification (as passed by php function)
* log - the log string passed from php notification
* args - This is the arguments that you passed on your notification method on php
* bIsTableMsg - is true when you use [[Main_game_logic:_yourgamename.game.php#NotifyAllPlayers|NotifyAllPlayers]] method (false otherwise)
* channelorig - information about table ID (formatted as : "/table/t[TABLE_NUMBER]")
* gamenameorig - name of the game
* move_id - ID of the move associated with the notification
* table_id - ID of the table (comes as string)
* time - UNIX GMT timestamp
* uid - unique identifier of the notification
* h - unknown

'' Note that those information were inferred from observation on console log. If an Admin can confirm/correct (and remove this line), you're welcome :)''

=== Ignoring notifications ===

Sometimes you need to ignore some notification on client side. You don't want them to be shown in game log and you don't want them to be handled.

The most common use case is when a player gets private information. They will receive a specific notification (such as "You received Ace of Heart"), while other players would receive more generic notification ("Player received a card").

In X.game.php
<pre>
$this->notifyAllPlayers("dealCard", clienttranslate('${player_name} received a card'), [
'player_id' => $playerId,
'player_name' => $this->getActivePlayerName()
]);

$this->notifyPlayer($playerId, "dealCardPrivate", clienttranslate('You received ${cardName}'), [
"type" => $card["type"],
"cardName" => $this->getCardName($card["type"])
]);
</pre>

The problem with this approach is that the active player will receive two notifications:
* Player1 received a card
* You received Ace of Hearts

Hence, notification ignoring.

NOTE: You can think that it would be possible to send such notification to all players except active just by using notifyPlayer and it seems to work. The problem however is that table spectators would miss such notification and their user interface (and game log) wouldn't be updated. Since there is no way to send notification just to spectators, ignoring the notification (or "filtering") is the only reasonable solution.

'''setIgnoreNotificationCheck(notif_type: string, predicate: ((notif: Notif)=>boolean))'''

This method will set a check whether any of notifications of specific type should be ignored.

The parameters are:
* notif_type: type of the notification
* predicate (notif => boolean): a function that will receive notif object and will return true if this specific notification should be ignored

Before dispatching any notification of this type, the framework will call predicate to check whether notification should be ignored, if it return true - the notification will be dispatched, i.e. logged or handled.

<pre>
this.notifqueue.setIgnoreNotificationCheck( 'dealCard', (notif) => (notif.args.player_id == this.player_id) );
</pre>

IMPORTANT: Remember that this notification is ignored on the client side, but was still received by the client. Therefore it shouldn't contain any private information as cheaters can get it. In other words this is not a way to hide information.

IMPORTANT: When a game is reloaded with F5 or when opening a turn based game, old notifications are replayed as history notification. They are used just to update the game log and are stripped of all arguments except player_id, i18n and any argument present in message. If you use and other argument in your predicate you should '''preserve''' it as explained [[Main_game_logic:_yourgamename.game.php#Notify_players|here]].

=== Synchronous notifications ===

When several notifications are received by your game interface, these notifications are processed immediately, one after the other, in the same exact order they have been generated in your PHP game logic.

However, sometimes, you need to give some time to the players to figure out what happened on the game before jumping to the next notification. Indeed, in many games, there are a lot of automatic actions, and the computer is going to resolve all these actions very fast if you don't tell it not to do so.

As an example, for Reversi, when someone is playing a disc, we want to wait 500 milliseconds before doing anything else in order the opponent player can figure out what move has been played.

Here's how we do this, right after our subscription:
<pre>
dojo.subscribe( 'playDisc', this, "notif_playDisc" );
this.notifqueue.setSynchronous( 'playDisc', 500 ); // Wait 500 milliseconds after executing the playDisc handler
</pre>

-----

It is also possible to control the delay timing dynamically (e.g., using notification args). As an example, maybe your notification 'cardPlayed' should pause for a different amount of time depending on the number or type of cards played.

For this case, use '''setSynchronous''' without specifying the duration and use '''setSynchronousDuration''' within the notification callback.

* NOTE: If you forget to invoke '''setSynchronousDuration''', the game will remain paused forever!

<pre>
setupNotifications: function () {
dojo.subscribe( 'cardPlayed', this, 'notif_cardPlayed' );
this.notifqueue.setSynchronous( 'cardPlayed' ); // wait time is dynamic
...
},

notif_cardPlayed: function (notif) {
// MUST call setSynchronousDuration

// Example 1: From notification args (PHP)
this.notifqueue.setSynchronousDuration(notif.args.duration);
...

// Or, example 2: Match the duration to a Dojo animation
var anim = dojo.fx.combine([
...
]);
anim.play();
this.notifqueue.setSynchronousDuration(anim.duration);
},
</pre>

You can also manually call this.notifqueue.setSynchronousDuration(0) once client operations are finished, but be careful that even fast replay still has a path to call it.

'''WARNING: combining synchronous and ignored notifications'''
You must be careful when combining dynamic synchronous durations (as described above) with ignored notifications. If you have a conditionally ignored notification like this (see below section):

<pre>this.notifqueue.setIgnoreNotificationCheck( 'myNotif', (notif) => (notif.args.player_id == this.player_id) /* or any other condition */ )</pre>

then you CANNOT do

<pre>this.notifqueue.setSynchronous('myNotif');</pre>

as, when the ignored check passes, the notification handler, in which `this.notifqueue.setSychronousDuration` is called, is never called and so the duration is never set and interface locking results.

The workaround is to set a "dummy" time:

<pre>this.notifqueue.setSynchronous('myNotif', 5000);</pre>

whose value is irrelevant but must be large enough to cover the time before the notification handler is called. The large value never actually comes into play because the notification is either ignored, or the synchronous duration is reset to a sensible value inside the handler.

=== Pre-defined notification types ===

'''tableWindow''' - This defines notification to display [[Game_interface_logic:_yourgamename.js#Scoring_dialogs|Scoring Dialogs]], see below.

'''message''' - This defines notification that shows on players log and have no other effect (technically any unhandled notification will do the same but its recommended to use this keyword for consistency)

// You can call this on php side without doing anything on client side
self::notifyAllPlayers( 'message', clienttranslate('hello'), [] );

'''simplePause''' - This notification will just delay other notifications, maybe useful if you know you need some extra time for animation or something. Requires a time parameter.

<pre>
self::notifyAllPlayers( 'simplePause', '', [ 'time' => 500] ); // time is in milliseconds
</pre>

Note: the following types are RESERVED by framework, do not use:

gameStateChange gameStateChangePrivateArg gameStateMultipleActiveUpdate newActivePlayer playerstatus yourturnack clockalert tableInfosChanged playerEliminated tableDecision archivewaitingdelay end_archivewaitingdelay replaywaitingdelay end_replaywaitingdelay replayinitialwaitingdelay end_replayinitialwaitingdelay aiPlayerWaitingDelay replay_has_ended updateSpectatorList wouldlikethink updateReflexionTime undoRestorePoint resetInterfaceWithAllDatas zombieModeFail zombieModeFailWarning aiError skipTurnOfPlayer zombieBack allPlayersAreZombie gameResultNeutralized playerConcedeGame showTutorial showCursor showCursorClick skipTurnOfPlayerWarning banFromTable resultsAvailable switchToTurnbased newPrivateState infomsg

== Tooltips ==

=== Adding static tooltips ===

'''this.addTooltip(nodeId: string, helpStringTranslated: string, actionStringTranslated: string, delay?: number): void'''

Add a simple text tooltip to the DOM node.

Specify 'helpStringTranslated' to display some information about "what is this game element?".
Specify 'actionStringTranslated' to display some information about "what happens when I click on this element?".

You must specify both of the strings. You can only use one and specify an empty string ('') for the other one.

When you pass text directly function _() must be used for the text to be marked for translation! Except for empty string.

Parameter "delay" is optional. It is primarily used to specify a zero delay for some game element when the tooltip gives really important information for the game - but remember: no essential information must be placed in tooltips as they won't be displayed in some browsers (see [[BGA_Studio_Guidelines|Guidelines]]).

Example:
<pre>
this.addTooltip( 'cardcount', _('Number of cards in hand'), '' );
</pre>

Note: this generates static tooltip and attaches to existing dom element, if you need to generate tooltip more dynamically you have to call that method every time information about object is updated or use completely different tehnique, see dynamic tooltips below.

'''this.addTooltipHtml(nodeId: string, html: string, delay?: number): void'''

Add an HTML tooltip to the DOM node (for more elaborate content such as presenting a bigger version of a card).

'''this.addTooltipToClass(cssClass: string, helpStringTranslated: string, actionStringTranslated: string, delay?: number ): void'''

Add a simple text tooltip to all the DOM nodes set with this cssClass. See more details above for this.addTooltip.
this.addTooltipToClass( 'meeple', _('This is A Meeple'), _('Click to tickle') );

IMPORTANT: all concerned nodes must exist and have IDs to get tooltips.

'''this.addTooltipHtmlToClass(cssClass: string, html: string, delay?: number): void'''

Add an HTML tooltip to to all the DOM nodes set with this cssClass (for more elaborate content such as presenting a bigger version of a card).

IMPORTANT: all concerned nodes must exist and have IDs to get tooltips.

=== Removing static tooltips ===

'''this.removeTooltip(nodeId: string): void'''

Remove a tooltip from the DOM node with given id.

=== Advanced tooltips ===

'''force tooltip to open'''

If you want to force tooltip to open in reaction to some other action, i.e. click you can do this

this.tooltips[id].open(id)

where id is the id of the tooltip node where tooltip was installed.

'''dynamic tooltips'''

See [[BGA_Studio_Cookbook#Dynamic_tooltips]]

'''tooltips on mobile'''

Tooltips is very unreliable on mobile, it is recommended to implement some other method to obtaining same information,
such as simple click handler in dedicated "Help" mode or provide dedicated clickable areas such as corner of card.

== Warning messages ==

Sometimes, there is something important that is happening in the game and you have to make sure all players get the message. Most of the time, the evolution of the game situation or the game log is enough, but sometimes you need something more visible.

Ex: someone fulfills one of the end of the game conditions, so this is the last turn.

'''this.showMessage(msg: string, type: string): void'''

showMessage shows a message in a big rectangular area on the top of the screen of the current player, and it dissapears after few seconds (also it will be in the log in some cases).

* "msg" is the string to display. It should be translated.
* "type" can be set to "info", "error", "only_to_log" or custom string. If set to "info", the message will be an informative message on a white background. If set to "error", the message will be an error message on a red background and it will be added to log. If set to "only_to_log", the message will be added to the game log but will not popup at the top of the screen.
If set to custom string, it will be transparent, to use custom type define "head_xxx" in css, where xxx is the type. For example if you want yellow warning, use "warning" as type and add this to css:
.head_warning {
background-color: #e6c66e;
}

Important: the normal way to inform players about the progression of the game is the game log. The "showMessage" is intrusive and should not be used often.

<pre>
notif_messageinfo: function(notif) {
if (!g_archive_mode) {
var message = this.format_string_recursive(notif.log, notif.args);
this.showMessage(_('Announcement:') + " " + message, 'info');
}
},
</pre>

Show message could be used on the client side to prevent user wrong moves before it is send to server.
Example from 'battleship':
<pre>
onGrid: function(event) {
if (checkIfPlayerTriesToFireOnThemselves(event)) {
this.showMessage(_('This is your own board silly!'), 'error');
return;
}
...
},
</pre>

'''this.showMoveUnauthorized(): void'''

Shows predefined user error that move is unauthorized now

<pre>
onPet: function(event) {
if (checkPet(event)==false) {
this.showMoveUnauthorized();
return;
}
...
},
</pre>

== Dialogs ==

=== Confirmation dialog ===

When an important action with a lot of consequences is triggered by the player, you may want to propose a confirmation dialog.

CAREFUL: the general guideline of BGA is to AVOID the use of confirmation dialogs. Confirmation dialogs slow down the game and bother players. The players know that they have to pay attention to each move when they are playing online.

The situations where you should use a confirmation dialog are the following:
* It must not happen very often during a game.
* It must be linked to an action that can really "kill a game" if the player does not pay attention.
* It must be something that can be done by mistake (ex: a link on the action status bar).

'''this.confirmationDialog(message: string, yesHandler: (param: any) => void, noHandler?: (param: any) => void, param?: any): void'''

* message - message will be shown to user, use _() to translate
* yesHandler - non-optional handler to be called on yes
* noHandler - optional handler to called on no
* param - if specified, it will be passed to both handlers
NOTE: this is async function, it does not return anything and you should not do anything after, you must do everything in handlers

How to display a confirmation dialog:
<pre>
this.confirmationDialog(_("Are you sure you want to bake a pie?"), () => {
this.bakeThePie();
});
return; // nothing should be called or done after calling this, all action must be done in the handler
</pre>
With param and both handlers
<pre>
this.confirmationDialog(_("Are you sure you want to bake a pie?"),
(ingredient) => this.bakeThePie(ingredient),
(ingredient) => console.log(`cancelled baking of ${ingredient}`),
'apple');
</pre>

=== Multiple choice dialog ===

You can use this dialog to give user a choice with small amount of options

'''this.multipleChoiceDialog(message: string, choices: string[], callback: (choice: number) => void): void'''
* message - message will be shown to user, use _() to translate
* choices - array of choices
* callback - non-optional handler to be called on choice made, the choice parameter is the INDEX of the choice from the array of choices

NOTE: this is async function, it does not return anything and you should not do anything after, you must do everything in handlers
NOTE: there is no cancel handler, so make sure you gave user a choice to get out of it

Example:
<pre>
const keys = ["0", "1", "5", "10"];
this.multipleChoiceDialog(_("How many bugs to fix?"), keys, (choice) => {
if (choice==0) return; // cancel operation, do not call server action
var bugchoice = keys[choice]; // choice will be 0,1,2,3 here
this.bgaPerformAction("fixBugs", { number: bugchoice });
});
return; // must return here
</pre>

=== Generic Dialogs ===

As a general rule, you shouldn't use dialogs windows.

BGA guidelines specify that all game elements should be displayed on the main screen. Players can eventually scroll down to see game elements they don't need to see anytime, and you may eventually create anchors to move between game area section. Of course dialogs windows are very practical, but the thing is: all players know how to scroll down, and not all players know how to show up your dialog window. In addition, when the dialog shows up, players can't access the other game components.

Sometimes although, you need to display a dialog window. Here is how you do this:

// Create the new dialog over the play zone. You should store the handler in a member variable to access it later
this.myDlg = new ebg.popindialog();
this.myDlg.create( 'myDialogUniqueId' );
this.myDlg.setTitle( _("my dialog title to translate") );
this.myDlg.setMaxWidth( 500 ); // Optional

// Create the HTML of my dialog.
// The best practice here is to use [[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl#Javascript_templates|Javascript templates]]
var html = this.format_block( 'jstpl_myDialogTemplate', {
arg1: myArg1,
arg2: myArg2,
...
} );

// Show the dialog
this.myDlg.setContent( html ); // Must be set before calling show() so that the size of the content is defined before positioning the dialog
this.myDlg.show();

// Now that the dialog has been displayed, you can connect your method to some dialog elements
// Example, if you have an "OK" button in the HTML of your dialog:
dojo.connect($('my_ok_button'), 'onclick', this, (event) => {
event.preventDefault();
this.myDlg.destroy();
});

If necessary, you can remove the default top right corner 'close' icon, or replace the function called when it is clicked:
// Removes the default close icon
this.myDlg.hideCloseIcon();

// Replace the function call when it's clicked
this.myDlg.replaceCloseCallback((event) => { ... });

=== Scoring dialogs ===

Sometimes at the end of a round you want to display a big table that details the points wins in each section of the game.

Example: in Hearts game, we display at the end of each round the number of "heart" cards collected by each player, the player who collected the Queen of Spades, and the total number of points loose by each player.

Scoring dialogs are managed entirely on '''PHP side''', but they are described here as their effects are visible only on client side.

Displaying a scoring dialog is quite simple and is using a special notification type: "tableWindow":
<pre>
// on PHP side:
$this->notifyAllPlayers( "tableWindow", '', array(
"id" => 'finalScoring',
"title" => clienttranslate("Title of the scoring dialog"),
"table" => $table
));
</pre>

The "table" argument is a 2 dimensional PHP array that describes the table you want to display, line by line and column by column.

Example: display an 3x3 array of strings
<pre>
$table = [
[ "one", "two", "three" ], // This is my first line
[ "four", "five", "six" ], // This is my second line
[ "seven", "height", "nine" ] // This is my third line
];
</pre>

As you can see above, in each "cell" of your array you can display a simple string value. But you can also display a complex value with a template and associated arguments like this:
<pre>
$table = [
[ "one", "two", [ "str" => clienttranslate("a string with an ${argument}"), "args" => [ 'argument' => 'argument_value' ] ] ],
[ "four", "five", "six" ],
[ "seven", "height", "nine" ]
];
</pre>

This is especially useful when you want to display player names with colors. Example from "Hearts":
<pre>
$firstRow = [ '' ];
foreach( $players as $player_id => $player ) {
$cell = [ 'str' => '${player_name}',
'args' => [ 'player_name' => $player['player_name'] ],
'type' => 'header'
];
$firstRow[] = $cell;
}
$table[] = $firstRow;
...
</pre>

You can also use three extra attributes in the parameter array for the notification:
* '''header''': the content for this parameter displays before the table (also, the html will be parsed and player names will be colored according to the current game colors).
* '''footer''': the content for this parameter displays after the table (no parsing for coloring the player names)
* '''closing''': if this parameter is used, a button will be displayed with this label at the bottom of the popup and will allow players to close it (more easily than by clicking the top right 'cross' icon).

<pre>
$this->notifyAllPlayers( "tableWindow", '', [
"id" => 'finalScoring',
"title" => clienttranslate("Title of the scoring dialog"),
"table" => $table,
"header" => ['str' => clienttranslate('Table header with parameter ${number}'),
'args' => [ 'number' => 3 ],
],
"footer" => '<div class="myfoot"></div>',
"closing" => clienttranslate( "Closing button label" )
] );
</pre>

Note: currently id is not used - so you cannot access resulting div by id on js side
Note: any traslatable stirng have to be wrapped by clienttranslate() on top level OR it has to be recursive template.

DO NOT DO THIS:
<pre>
"footer" => '<div>'.clienttranslate( "The end" ).'</div>', // this will not work for translations!!!
</pre>

=== Scoring animated display ===

Sometimes, you may want to display a score value over an element to make the scoring easier to follow for the players (Terra Mystica final scoring for example).
You can do it with:

'''this.displayScoring(anchor_id: string, color: string, score: number | string, duration?: number, offset_x?: number, offset_y?: number): void'''

'''anchor_id''': ID of the html element to place the animated score onto (without the '#')

'''color''': hexadecimal RGB representation of the color (should be the color of the scoring player), but without a leading '#'. For instance, 'ff0000' for red.

'''score''': numeric score to display, prefixed by a '+' or '-'

'''duration''': animation duration in milliseconds (optional, default is 1000)

'''offset_x''' and '''offset_y''': if both offset_x and offset_y are defined and not null, apply the following offset (in pixels) to the scoring animation.
Note that the score is centered in the anchor, so the offsets might have to be negative if you calculate the position.

Note: if you want to display successively each score, you can use ''this.notifqueue.setSynchronous()'' function.
<pre>
setupNotifications: function() {
dojo.subscribe( 'displayScoring', this, "notif_displayScoring" );
...
}
...

notif_displayScoring: function(notif) {
const duration = notif.args.duration?notif.args.duration:1000;
this.notifqueue.setSynchronous('displayScoring', duration );
this.displayScoring( notif.args.target, notif.args.color, notif.args.score, duration);
},
</pre>

=== Speech bubble ===

For better interactivity in some games (Love Letter for example), you may use comic book style speech bubbles to express the players voices.
This is done with showBubble:

'''this.showBubble(anchor_id: string, text: string, delay?: number, duration?: number, custom_class?: string): void'''

* anchor_id - where to attach the bubble
* text - what to put in bubble, can be html
* delay - delay in milliseconds (optional, default 0)
* duration - duration of animation in milliseconds (optional, default 3000)
* custom_class - extra class to add to bubble (optional), if you need to override the default bubble style

<pre>
this.showBubble('meeple_2', _('Hello'), 0, 1000, 'pink_bubble');
</pre>

<pre>
notif_speechBubble(notif) {
var html = this.format_string_recursive(notif.args.text, notif.args.args);
this.showBubble(notif.args.target, html, notif.args.delay ?? 0, notif.args.duration ?? 1000);
},
</pre>

'''Warning''': if your bubble could overlap other active elements of the interface (buttons in particular), as it stays in place even after disappearing, you should use a custom class to give it the style "pointer-events: none;" in order to intercept click events.

Note: If you want this visually, but want to take complete control over this bubble and its animation (for example to make it permanent) you can just use div with 'discussion_bubble' class on it, and content of div is what will be shown.

== Translations ==

See [[Translations]]

== Players panels ==

=== Update players score ===

The column player_score from the player table is automatically loaded into this.scoreCtrl and therefore into the stars location on the player board. This occurs sometime after the game setup() function. However this score must be updated as the game progresses using notifications.

Note: this.scoreCtrl[player_id] is object of class [[Counter]], you can use other counter API.

Increase a player score (with a positive or negative number):

<pre>
this.scoreCtrl[ player_id ].incValue( score_delta );
</pre>

Set a player score to a specific value:

<pre>
this.scoreCtrl[ player_id ].setValue( new_score );
</pre>

Set a player score to a specific value with animation:

<pre>
this.scoreCtrl[ player_id ].toValue( new_score );
</pre>

Typical usage would be (that will process 'score' notification):
<pre>
setupNotifications : function() {
...
dojo.subscribe('score', this, "notif_score");
},
notif_score: function(notif) {
this.scoreCtrl[notif.args.player_id].setValue(notif.args.player_score);
},
</pre>

=== Adding stuff to player's panel ===

At first, create a new "JS template" string in your template (tpl) file:

(from Gomoku example)
<pre>
var jstpl_player_board = '\<div class="cp_board">\
<div id="stoneicon_p${id}" class="gmk_stoneicon gmk_stoneicon_${color}"></div><span id="stonecount_p${id}">0</span>\
</div>';
</pre>

Then, you add this piece of code in your JS file to add this template to each player panel:

<pre>
// Setting up player boards
for( var player_id in gamedatas.players )
{
var player = gamedatas.players[player_id];

// Setting up players boards if needed
var player_board_div = $('player_board_'+player_id);
dojo.place( this.format_block('jstpl_player_board', player ), player_board_div );
}
</pre>

(Note: the code above is of course from your "setup" function in your Javascript).

Very often, you have to distinguish current player and others players. In this case, you just have to create another JS template (ex: jstpl_otherplayer_board) and use it when "player_id" is different than "this.player_id".

=== Fixing Player Panel heights ===

You may find that the player panels don't automatically resize when adding something to (or removing something from) a player panel while the display is in portrait mode (i.e. the player summary panels are at the top of the screen rather than down the right side).

When this happens, call <pre>this.adaptPlayersPanels();</pre> This recalculates the layout and also adjusts the position of the actionbar for you.

=== Player's panel disabling/enabling ===

'''this.disablePlayerPanel(player_id: number): void'''

Disable given player panel (the panel background become gray).

Usually, this is used to signal that this played passes, or will be inactive during a while.

Note that the only effect of this is visual. There are no consequences on the behaviour of the panel itself.

'''this.enablePlayerPanel(player_id:number): void'''

Enable a player panel that has been disabled before.

'''this.enableAllPlayerPanels(): void'''

Enable all player panels that has been disabled before.

=== Player order ===

'''this.updatePlayerOrdering(): void'''

This function makes sure that player order in player's panel matches this.gamedatas.playerorder and its normally called by framework.
You can call it yoursel if you change this.gamedatas.playerorder from notification.
Also you can override this function to change defaults OR insert a non-player panel [[BGA_Studio_Cookbook#Inserting_non-player_panel]].

=== Counters ===
Note: there is bga component called "ebg/counter" this API is not using it, these methods
below declared right in core game. If you need animation for counters use ebg/counter

To use this API just create a counter dom element like this (class does not really matter)
<pre>
<div class="counter" id="bread"></div>
<div class="counter" id="coin"></div>
</pre>
The "bread" will the counter name.

The php code should send all "counters" data from getAllDatas() method like this

game.php
<pre>
protected function getAllDatas() {
// (the key must match counter_name)
$result['counters']=[
'bread' => [
'counter_name' => 'bread',
'counter_value' => 3
],
'coin' => [
'counter_name' => 'coin',
'counter_value' => 5
]
];
return $result;
}
</pre>

'''setCounter(counter_name: stirng, new_value: string | number): void'''

updates the global this.gamedatas.counters and value of node $(counter_name)
<pre>
notif_counter: function(notif) {
this.setCounter(notif.args.counter_name, notif.args.counter_value);
},
</pre>

'''incCounter(counter_name: string, delta: number): void'''
<pre>
notif_counter : function(notif) {
this.incCounter(notif.args.counter_name, notif.args.inc);
},
</pre>

'''updateCounters(counters: object): void'''

Useful for updating game counters in the player panel (such as resources).
'counters' arg is map of counters (the key must match counter_name)
{
'bread': {
'counter_name' : 'bread',
'counter_value' => 3
},
'coin': {
'counter_name' : 'coin',
'counter_value' => 5
}
}
All counters MUST be referenced in this.gamedatas.counters (means they should be send from php) and will be updated.
DOM objects referenced by 'counter_name' will have their innerHTML updated with 'counter_value'.

Usually you call this from notification

<pre>
notif_counter : function(notif) {
this.updateCounters(notif.args.counters);
},
</pre>

== BGA GUI components ==

BGA framework provides some useful ready-to-use components for the game interface:

[[Studio#BGA_Studio_game_components_reference]]

Note that each time you are using an additional component, you must declare it at the top of your Javascript file in the list of modules used.

Example if you are using "ebg.stock":
<pre>
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/stock" /// <=== we are using ebg.stock module
],
</pre>

== BGA Buttons ==

=== Basic Button ===

'''this.addActionButton(id: string, label: string, method: string | eventhandler, destination?: string, blinking?: boolean, color?: string): void'''

You can use this method to add an action button in the main action status bar (or other places).

Arguments:
* id: an element ID that should be unique in your HTML DOM document.
* label: the text of the button. Should be translatable (use _() function). Note: this can also be any html, such as "<div class='brick'></div>", see example below on how to make image action buttons.
* method: the name of your method that must be triggered when the player clicks on this button (can be name of the method on game class or handler).
* destination (optional): id of parent on where to add button, ONLY use in rare cases if location is not action bar. Use '''null''' as value if you need to specify other arguments.
* blinking (optional): if set to '''true''', the button is going blink to catch player's attention. Please DO NOT abuse blinking button. If you need button to blink after some time passed add class 'blinking' to the button later.
* color: could be '''blue''' (default), '''red''','''gray''' or '''none'''.

You should only use this method in your "onUpdateActionButtons" method. Usually, you use it like this:

<pre>
onUpdateActionButtons: function( stateName, args ) {
if (this.isCurrentPlayerActive()) {
switch( stateName ) {
case 'giveCards':
this.addActionButton( 'giveCards_button', _('Give selected cards'), 'onGiveCards' );
this.addActionButton( 'pass_button', _('Pass'), () => this.bgaPerformAction('actPass') );
break;
}
}
},
</pre>

In the example above, we are adding a "Give selected cards" button in the case we are on game state "giveCards". When player clicks on this button, it triggers our "onGiveCards" method.

Example using blinking red button:
<pre>
this.addActionButton( 'button_confirm', _('Confirm?'), 'onConfirm', null, true, 'red');
</pre>

If you want to call the handler with arguments, you can use arrow functions, like this:
<pre>
this.addActionButton( 'commit_button', _('Confirm'), () => this.onConfirm(this.selectedCardId), null, false, 'red');
</pre>

=== Image Button ===

You can use the same method, but add extra class to a button to disable the padding and style it, i.e.
<pre>
this.addActionButton( 'button_brick', '<div class="brick"></div>', ()=>{... on brick ...}, null, null, 'gray');
dojo.addClass('button_brick','bgaimagebutton');
</pre>

where

<pre>
.bgaimagebutton {
padding: 0px 12px;
min-height: 28px;
border: none;
}
</pre>

If you use this a lot, you can define a helper function, i.e.
<pre>
/**
* This method can be used instead of addActionButton, to add a button which is an image (i.e. resource). Can be useful when player
* need to make a choice of resources or tokens.
*/
addImageActionButton: function(id, div, handler, bcolor, tooltip) {
if (typeof bcolor == "undefined") {
bcolor = "gray";
}
// this will actually make a transparent button id color = gray
this.addActionButton(id, div, handler, null, false, bcolor);
// remove border, for images it better without
dojo.style(id, "border", "none");
// but add shadow style (box-shadow, see css)
dojo.addClass(id, "shadow bgaimagebutton");
// you can also add additional styles, such as background
if (tooltip) {
dojo.attr(id, "title", tooltip);
}
return $(id);
},
</pre>

=== Disabling Button ===

You can disable the '''bgabutton''' by adding the css class '''disabled''' in you js. The disabled button is still visible but is grey and not clickable.
For example in the '''onUpdateActionButtons''' :
<pre>
this.addActionButton('play_button_id', _('Play 1 to 3 cards'), 'playFunctionButton');
if (condition) {
dojo.addClass('play_button_id', 'disabled');
}
</pre>

=== Custom Buttons ===

You can create a custom button, but the BGA framework provides a standard button that requires only .css classes: '''bgabutton''' and '''bgabutton_${color}'''.

'''Examples:'''

<pre>
<a href="#" id="my_button_id" class="bgabutton bgabutton_blue"><span>My blue button</span></a>

<a href="#" id="my_button_id" class="bgabutton bgabutton_red bgabutton_big"><span>My big red button</span></a>
</pre>

'''Note''': To see it in action, check out ''Coloretto''.

=== Button outside of action bar ===

Use addActionButton() method with destination argument set
<pre>
this.addActionButton( 'commit_button', _('Confirm'), 'onConfirm', 'player_board', true, 'red');
</pre>

in example above the button will be place on object with id 'player_board'

== Image loading ==

See also [[Game_art:_img_directory]].

'''Be careful''': by default, ALL images of your img directory are loaded on a player's browser when he loads the game. For this reason, don't let in your img directory images that are not useful, otherwise it's going to slowdown the game load.

'''this.dontPreloadImage(image_file_name: string)'''

Using dontPreloadImage, you tell the interface to not preload a specific image in your img directory.

Example of use:
<pre>
this.dontPreloadImage( 'cards.png' );
</pre>

This is particularly useful if for example you have 2 different themes for a game. To accelerate the loading of the game, you can specify to not preload images corresponding to the other theme.

Another example of use: in "Gosu" game with Kamakor extension, you play with 5 sets of cards among 10 available. Cards images are organized by sets, and we only preload the images corresponding to the 5 current sets with '''ensureSpecificGameImageLoading( image_file_names_array )'''.
<pre>
// By default, do not preload anything
this.dontPreloadImage( 'cards.png' );
this.dontPreloadImage( 'clan1.png' );
this.dontPreloadImage( 'clan2.png' );
this.dontPreloadImage( 'clan3.png' );
this.dontPreloadImage( 'clan4.png' );
this.dontPreloadImage( 'clan5.png' );
this.dontPreloadImage( 'clan6.png' );
this.dontPreloadImage( 'clan7.png' );
this.dontPreloadImage( 'clan8.png' );
this.dontPreloadImage( 'clan9.png' );
this.dontPreloadImage( 'clan10.png' );
var to_preload = [];
for( i in this.gamedatas.clans )
{
var clan_id = this.gamedatas.clans[i];
to_preload.push( 'clan'+clan_id+'.png' );
}

this.ensureSpecificGameImageLoading( to_preload );

</pre>

'''Note:''' You don't need to specify to not preload game box images (game_box.png, game_box75.png...) since they are not preloaded by default.

'''this.ensureSpecificGameImageLoading(list: string[])'''

This is oppostive of dontPreloadImage - its ensure specific images is loaded. Note: only makes sense if preload list is empty, otherwise everything is loaded anyway

'''load specific images'''
All images that will be preloaded stored in g_img_preload. If you want to override it directly - there is no API, but you can do this in GAME constructor

g_img_preload = ['tokens.png', 'trains.png', 'loc_plan.png', 'eng.png', 'eng-back.png'];

You can also set it to empty array and call ensureSpecificGameImageLoading() on specific images

== Sounds ==

Add a custom sound and make it load with your interface:

Add this in your template (.tpl) file:
<pre>
<audio id="audiosrc_<gamename>_<yoursoundname>" src="{GAMETHEMEURL}img/<gamename>_<yoursoundname>.mp3" preload="none" autobuffer></audio>
<audio id="audiosrc_o_<gamename>_<yoursoundname>" src="{GAMETHEMEURL}img/<gamename>_<yoursoundname>.ogg" preload="none" autobuffer></audio>
</pre>

Note: this is a requirement to provide both a mp3 and a ogg file with the names <code><gamename>_<yoursoundname>[.ogg][.mp3]</code>.

Play the sound (from your .js file):

<pre>
playSound('<gamename>_<yoursoundname>'); // do not add 'this.' - its a global function
</pre>

Disable the standard "move" sound for this move (to replace it with your custom sound):

Add this to your notification handler:

<pre>
this.disableNextMoveSound();
</pre>

Note: it only disable the sound for the next move.

== Title bar and states ==

=== Client states ===

Client states is a way to simulate the state transition but without actually going
to server. It is usefull when you need to ask user multiple questions before you
send things to server

'''this.setClientState(newState: string, args: object)'''

Example:
this.setClientState("client_playerPicksLocation", {
descriptionmyturn : _("${you} must select location"),
});

For more information see [[BGA_Studio_Cookbook#Multi_Step_Interactions:_Select_Worker.2FPlace_Worker_-_Using_Client_States]]

'''this.restoreServerGameState()'''
If you are in client state it will restore the current server state (cheap undo)

'''this.on_client_state'''
Boolean indicating that we are in client state

=== Title bar ===
If you simply want to show something in title bar you can do it directly
$('pagemaintitletext').innerHTML = text;

This however will not work with parameters and will not draw You in color,
if you want to do proper args rendering use method below

;'''this.removeActionButtons()'''
Removes all buttons from title bar

;'''this.updatePageTitle()'''
:This function allows to update the current page title and turn description according to the game state arguments. If the current game state description this.gamedatas.gamestate.descriptionmyturn is modified before calling this function it allows to update the turn description without changing state. This will handle arguments substitutions properly.

Note: this functional also will calls this.onUpdateActionButtons, if you want different buttons then state defaults, use method in example to replace them, if it becomes too clumsy use client states (see above)

Example from Terra Mystica:
<pre>
onClickFavorTile: function( evt ) {
...
if ( ... ) {
this.gamedatas.gamestate.descriptionmyturn = _('Special action: ') + _('Advance 1 space on a Cult track');
this.updatePageTitle();
this.removeActionButtons();
this.addActionButton( ... );
...
return;
}
...

}
</pre>

== User preferences ==
'''this.getGameUserPreference(pref_id)'''

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

'''this.setGameUserPreference(pref_id, value)'''

Programmatically change a user preference. It will have the same effect as if the player changed the value in the select combo box, in the top-right menu.

'''this.onGameUserPreferenceChanged'''

A callback you can define if you want to be notified when a user changes a user preference.

Example:<pre>
onGameUserPreferenceChanged: function(pref_id, pref_value) {
switch (pref_id) {
case 201:
document.getElementsByTagName('html')[0].classList.toggle('dark-background', pref_value == 2);
break;
}
}
</pre>

== Other useful stuff ==

'''dojo.hitch'''

With dojo.hitch, you can create a callback function that will run with your game object context whatever happen.

Typical example: display a BGA confirmation dialog with a callback function created with dojo.hitch:

<pre>
this.confirmationDialog( _('Are you sure you want to make this?'), dojo.hitch( this, function() {
this.bgaPerformAction('makeThis');
} ) );
</pre>

In the example above, using dojo.hitch, we ensure that the "this" object will be set when the callback is called.

NOTE: In modern JS there are lambdas that eliminate need for that, the example above will look like this
<pre>
this.confirmationDialog( _('Are you sure you want to make this?'), () => this.bgaPerformAction( 'makeThis') );
</pre>

;'''onScreenWidthChange()'''
:This function can be overridden in your game to manage some resizing on the client side when the browser window is resized. This function is also triggered at load time, so it can be used to adapt to the :viewport size at the start of the game too.

; this.bRealtime
: Return true if the game is in realtime. Note that having a distinct behavior in realtime and turn-based should be exceptional.

; g_replayFrom
: Global contains replay number in live game, it is set to undefined (i.e. not set) when it is not a replay mode, so consequentially the good check is '''typeof g_replayFrom != 'undefined'''' which returns true if the game is in replay mode <i>during the game</i> (the game is ongoing but the user clicked "replay from this move" in the log)

; g_archive_mode
: Returns true if the game is in archive mode <i>after the game</i> (the game has ended)

; this.instantaneousMode
: Returns true during replay/archive mode if animations should be skipped. Only needed if you are doing custom animations. (The BGA-provided animation functions like <i>this.slideToObject()</i> automatically handle instantaneous mode.)
: Technically, when you click "replay from move #20", the system replays the game from the very beginning with moves 0 - 19 happening in instantaneous mode and moves 20+ happening in normal mode.

; g_tutorialwritten
: Returns an object like the below if the game is in tutorial mode, or undefined otherwise. Tutorial mode is a special case of archive mode where comments have been added to a previous game to teach new players the rules.
{
author: "91577332",
id: "576",
mode: "view"
status: "alpha"
version_override: null
viewer_id: "84554161"
}

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

[[Category:Studio]]

Game interface logic: Game.js

2024-09-25T17:56:46Z

Sguzzer Gunayer: /* Connecting */

{{Studio_Framework_Navigation}}

__TOC__

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

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

== File structure ==

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

Here is the basic structure:

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

More details:

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

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

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

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

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

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

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

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

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

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

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

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

== Dojo framework ==

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

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

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

== Javascript minimization (after July 2020) ==

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

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

== Accessing Players Information ==

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

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

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

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

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

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

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

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

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

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

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

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

== Accessing and manipulating the DOM ==

=== Element by Id ===

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

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

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

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

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

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

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

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

=== Style ===

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

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

Examples:

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

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

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

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

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

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

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

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

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

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

=== Classes ===

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

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

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

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

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

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

Example from ''Reversi'':

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

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

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

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

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

'''Vanilla JS classList'''

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

=== Attributes ===

;dojo.attr

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

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

'''Vanilla JS attr'''

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

=== Queries ===

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

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

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

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

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

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

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

'''Vanilla JS query'''

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

=== Creating and Destroying elements ===

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

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

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

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

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

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

Create element

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

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

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

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

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

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

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

const div = ``;
'''this.format_string_recursive'''

This bga function is similar to this.format_string but is capable of processing recursive argument structures and translations. It is used to format server notifications.

TODO: find better place for these function docs

=== Moving elements ===

'''dojo.place(node: string | Element, refNode: ElementOrId, pos?: string | number): Element'''

dojo.place is the best function to insert HTML code somewhere in your game interface without breaking something. It is much better to use than the '''innerHTML=''' method if you must insert HTML tags and not only values.

node: can be a string or a DOM node. If it is a string starting with “<”, it is assumed to be an HTML fragment, which will be created. Otherwise it is assumed to be an id of a DOM node.

<pre>
// Insert your HTML code as a child of a container element
dojo.place( "<div class='foo'></div>", "your_container_element_id" );
</pre>

pos: optional argument. Can be a number or one of the following strings: “before”, “after”, “replace”, “only”, “first”, or “last”. If omitted, “last” is assumed.

* "replace": replace the container element with my_node element
* "first": places the node as a child of the reference node. The node is placed as the first child.
* "last" (default): places the node as a child of the reference node. The node is placed as the last child.
* "before": places the node right before the reference node.
* "after": places the node right after the reference node.
* "only": replaces all children of the reference node with the node.

this parameter can be a positive integer. In this case, the node will be placed as a child of the reference node with this number (counting from 0). If the number is more than number of children, the node will be appended to the reference node making it the last child.

<pre>
// Replace all children of container with my_node
dojo.place( $('my_node'), "your_container_element_id", "only" );
</pre>

See also full doc on dojo.place: [https://dojotoolkit.org/reference-guide/1.7/dojo/place.html]

Usually, when you want to insert some piece of HTML in your game interface, you should use "[[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl#Javascript_templates|Javascript templates]]".

But you can also relocate elements like that. Note: it won't animate if you do that.

'''this.placeOnObject(mobile_obj: ElementOrId, target_obj: ElementOrId): void'''

places mobile_obj on target_obj, set the absolute positions and centers the mobile_obj on target_obj,
effect is immediate

This is not really an animation, but placeOnObject is frequently used before starting an animation.

Example:
<pre>
// (We just created an object "my_new_token")

// Place the new token on current player board
this.placeOnObject( "my_new_token", "overall_player_board_"+this.player_id );

// Then slide it to its position on the board
this.slideToObject( "my_new_token", "a_place_on_board" ).play();
</pre>

'''this.placeOnObjectPos(mobile_obj: ElementOrId, target_obj: ElementOrId, target_x: number, target_y: number): void'''

This method works exactly like placeOnObject, except than you can specify some (x,y) coordinates (in px). This way, the center of "mobile_obj" will be placed to the specified x,y position relatively to the center of "target_obj".

''Note: the placement works differently from this.slideToObjectPos'', since coordinates are calculated based on the center of objects.

'''this.attachToNewParent(mobile_obj: ElementOrId, target_obj: ElementOrId): void'''

With this method, you change the HTML parent of "mobile_obj" element without moving it.
"target_obj" is the new parent of this element. The beauty of
attachToNewParent is that the mobile_obj element DOES NOT MOVE during this process.

What happens is that the method calculate a relative position of mobile_obj to make sure it does not move after the HTML parent changes.

Why using this method?

Changing the HTML parent of an element can be useful for the following reasons:
* When the HTML parent moves, all its child are moving with them. If some game elements is no more linked with a parent HTML object, you may want to attach it to another place.
* The z_order (vertical order of display) depends on the position in the DOM, so you may need to change the parent of some game elements when they are moving in your game area.

'''CAREFUL''': this function destroys original object and places a clone onto a new parent, this will break all references to this HTML element (ex: dojo.connect).
If you need version that does not destroy the object but the same otherwise see [[BGA_Studio_Cookbook#Attach_to_new_parent_without_destroying_the_object]]

== Animations ==

===Dojo Animations===

BGA animations is based on Dojo Animation ([http://dojotoolkit.org/documentation/tutorials/1.8/animation/ see tutorial here]).

However, most of the time, you can just use methods below, which are built on top of Dojo Animation.

Note: one interesting method from Dojo that could be useful from time to time is "Dojo.Animation". It allows you to make any CSS property "slide" from one value to another.

Note 2: the slideTo methods are not compatible with CSS transform (scale, zoom, rotate...). If possible, avoid using CSS transform on nodes that are being slided. Eventually, the only possible solution to make these 2 compatible is to disable all CSS transform properties, use slideToObjectPos/placeOnObjectPos, and then apply them again.

===Sliding===

'''this.slideToObject(mobile_obj: ElementOrId, target_obj: ElementOrId, duration?: number, delay?: number): Animation'''

You can use slideToObject to "slide" an element to a target position.

Sliding element on the game area is the recommended and the most used way to animate your game interface. Using slides allow players to figure out what is happening on the game, as if they were playing with the real boardgame.

The parameters are:
* mobile_obj: the ID of the object to move. This object must be "relative" or "absolute" positioned.
* target_obj: the ID of the target object. This object must be "relative" or "absolute" positioned. Note that it is not mandatory that mobile_obj and target_obj have the same size. If their size are different, the system slides the center of mobile_obj to the center of target_obj.
* duration: (optional) defines the duration in millisecond of the slide. The default is 500 milliseconds.
* delay: (optional). If you defines a delay, the slide will start only after this delay. This is particularly useful when you want to slide several object from the same position to the same position: you can give a 0ms delay to the first object, a 100ms delay to the second one, a 200ms delay to the third one, ... this way they won't be superposed during the slide.

BE CAREFUL: The method returns an dojo.fx animation, so you can combine it with other animation if you want to. It means that you have to call the "play()" method, otherwise the animation WON'T START.

Example:
<pre>
this.slideToObject( "some_token", "some_place_on_board" ).play();
</pre>

'''this.slideToObjectPos(mobile_obj: ElementOrId, target_obj: ElementOrId, target_x: number, target_y: number, duration?: number, delay?: number): Animation'''

This method does exactly the same as "slideToObject", except than you can specify some (x,y) coordinates. This way, "mobile_obj" will slide to the specified x,y position relatively to "target_obj".

Example: slide a token to some place on the board, 10 pixels from the top:
<pre>
this.slideToObjectPos( "some_token", "some_place_on_board", 0, 10 ).play();
</pre>

'''this.slideTemporaryObject(mobile_obj_html: string, parent: ElementOrId, from: ElementOrId, to: ElementOrId, duration?: number, delay?: number): Animation'''

This method is useful when you want to slide a temporary HTML object from one place to another. As this object does not exists before the animation and won't remain after, it could be complex to create this object (with dojo.place), to place it at its origin (with placeOnObject) to slide it (with slideToObject) and to make it disappear at the end.

slideTemporaryObject does all of this for you:
* mobile_obj_html is a piece of HTML code that represent the object to slide.
* parent is the ID of an HTML element of your interface that will be the parent of this temporary HTML object.
* from is the ID of the origin of the slide.
* to is the ID of the target of the slide.
* duration/delay works exactly like in "slideToObject"

Example:
<pre>
this.slideTemporaryObject( '<div class="token_icon"></div>', 'tokens', 'my_origin_div', 'my_target_div' ).play();
</pre>

===Destroy===
'''this.slideToObjectAndDestroy(mobile_obj: ElementOrId, target_obj: ElementOrId, duration?: number, delay?: number): void'''

This method is a handy shortcut to slide an existing HTML object to some place then destroy it upon arrival. It can be used for example to move a victory token or a card from the board to the player panel to show that the player earns it, then destroy it when we don't need to keep it visible on the player panel.

It works the same as this.slideToObject and takes the same arguments, but it starts the animation.

CAREFUL: Make sure nothing is creating the same object at the same time the animation is running, because this will cause some random disappearing effects

Example:
<pre>
this.slideToObjectAndDestroy( "some_token", "some_place_on_board", 1000, 0 );
</pre>

'''this.fadeOutAndDestroy( node: string | Element, duration?: number, delay?: number):''' '''void'''

This function fade out the target node, then destroy it. Its starts the animation.
* duration/delay works exactly like in "slideToObject"

Example:
<pre>
this.fadeOutAndDestroy( "a_card_that_must_disappear" );
</pre>

CAREFUL: the HTML node still exists until during few milliseconds, until the fadeOut has been completed.
Make sure nothing is creating same object at the same time as animation is running, because you will be some random dissapearing effects

===Rotating elements===

This example combines "Dojo.Animation" method and a CSS property transform that allow you to rotate the element.
<pre>
// node is Element we rotating
var animation = new dojo.Animation({
curve: [fromDegree, toDegree],
onAnimate: (v) => {
node.style.transform = 'rotate(' + v + 'deg)';
}
});

animation.play();
</pre>

BGA has its own interface to rotate

'''this.rotateTo(node: string | Element, degree: number): void'''

It starts the animation, and stored the rotation degree in the class, so next time you rotate object - it is additive.
There is no animation hooks in this one, if you need to change any parameters use dojo animation above.

There is also '''rotateInstantTo''' with same signature which does not animate

===Animation Callbacks===

If you wish to run some code only after an animation has completed you can do this by linking a callback method to 'onEnd'.

<pre>
var animation_id = this.slideToObject( mobile_obj, target_obj, 500 );
dojo.connect(animation_id, 'onEnd', () => {
// do something here
});
animation_id.play();
</pre>

If you wish to call a second animation after the first (rather than general code) then you can use a dojo animation chain (see tutorial referenced above).

== Players input ==

=== Connecting ===
'''dojo.connect(element: Element, event: string, context: object, method: eventHandler): any'''

'''dojo.connect(element: Element, event: string, handler: eventHandler): any'''

Used to associate a player event with one of your notification methods.

Example: associate a click on an element ("my_element") with one of our methods ("onClickOnMyElement"):
<pre>
dojo.connect( $('my_element'), 'onclick', this, 'onClickOnMyElement' );
</pre>

Same idea but based on query (i.e. all element of 'pet' class)
dojo.query(".pet").connect('onclick', this, 'onPet');

Note: if you need to disconnect the handler you have to store handler returned from this method, i.e.

<pre>
var handler = dojo.connect(...);
...
dojo.disconnect(handler);
</pre>

If you don't store the handler - you have to destroy the object to disconnect it

Typical function that implements the input handler will look like this

<pre>
onPet: function(event) {
var id = event.currentTarget.id;
console.log('onPet ' + id);
dojo.stopEvent(event);
if (this.gamedatas.gamestate.name == 'playerTurnPet') {
this.bgaPerformAction('actPlayPet', {card: id});
} else {
this.showMoveUnauthorized();
}
}
</pre>

'''this.connect(element: ElementOrId, event: string, method: eventHandler): void'''

Used to associate a player event with one of your notification methods.

this.connect( $('my_element'), 'onclick', 'onClickOnMyElement' );

Or you can use an in-place handler

this.connect( $('my_element'), 'onclick', (e) => { console.log('boo'); } );

Note that this function stores the connection handler. That is the only real difference between '''this.connect''' and '''dojo.connect'''. If you plan to destroy the element you connected, you '''must''' call this.disconnect() to prevent memory leaks.
This function is mainly for permanent objects - if you just want to connect the temp object you should probably not use this method but use dojo.connect which won't require any clean-up.

'''this.connectClass(cssClassName: string, event: string, method: eventHandler): void'''

Same as connect(), but for all the nodes set with the specified cssClassName.
this.connectClass('pet', 'onclick', 'onPet');
'''this.disconnect(element: ElementOrId, event: string): void'''

Disconnect event handler (previously registered with this.connect or this.connectClass).

this.disconnect( $('my_element'), 'onclick');

Note: dynamic connect/disconnect is for advanced cases ONLY, you should always connect elements statically if possible, i.e. in setup() method.

'''this.disconnectAll(): void'''

Disconnect all previously registed event handlers (registered via this.connect or this.connectClass)

this.disconnectAll();

=== Actions ===

'''this.bgaPerformAction(action: string, args?: object, options: object = { lock: true, checkAction: true }): Promise<void>'''

Triggers an action on the backend. This is a combination of checkAction and ajaxcall, returning a Promise which resoves when ajaxcall ends.

This method must be used to send a player input to the game server. '''It should not be triggered programmatically''', especially not in loops, in callbacks, in notifications, or in onEnteringState/onUpdateActionButtons/onLeavingState, in order not to create race conditions or break replay game and tutorial features. It should be used only in reaction to a user action in the interface.

* action: name of the action, as it is written in "possibleactions" of the current state.
* args: an object containing the call parameters to send to the action
* options: options to tweak the call with some defaults. Default is <code>{ lock: true, checkAction: true }</code>.

Example of a standard call without args:
this.bgaPerformAction('pass');

Example of a standard call with action args:
this.bgaPerformAction('actPlayCard', { id: this.selectedCardId });

Example of a call without checking action (because player is inactive in a multiactive state):

this.bgaPerformAction('actChangeMind', {}, { checkAction: false });

Example of a call without lock (because of a special action not directly related to the game flow):

this.bgaPerformAction('actSetAutoBid', { alwaysBidUntil: 500 }, { lock: false, checkAction: false });

Example of call with reaction to exception:
this.bgaPerformAction('actPlayCard', { id: this.selectedCardId }).catch(()=>{ this.selectedCardId = undefined; });

Example of call with reaction to success:
this.bgaPerformAction('actPlayCard', { id: this.selectedCardId }).then(()=>{ this.unselectAll(); });

'''this.ajaxcall(url, parameters, obj_callback, callback, callback_anycase?, ajax_method?: string)'''

''Note: bgaPerformAction is a simpler way to use ajax calls, ajaxcall stays in the doc for legacy reasons only and should not be used in new projects.''

Same warning as '''this.bgaPerformAction''' about using on user action only.

* url: the url of the action to perform. For a game, it must be: "/<mygame>/<mygame>/myAction.html"
* parameters: an array of parameter to send to the game server.
** Note that "lock: true" must always be specified in this list of parameters in order the interface can be locked during the server call. Cannot use lock: false - to not lock it has to be undefined.
** Note: Restricted parameter names (please don't use them):
*** "action"
*** "module"
*** "class"
* obj_callback: must be set to "this".
* callback (non-optional but rarely used): a function to trigger when the server returns result and everything went fine (not used, as all data handling is done via notifications).
* callback_anycase: (optional) a function to trigger when the server returns ok OR error. If no error this function is called with parameter value false. If an error occurred, the first parameter will be set to true, the second will contain the error message sent by the PHP back-end, and the third will contain an error code.
* ajax_method: (optional and rarely used) if you need to send large amounts of data (over 2048 bytes), you can set this parameter to 'post' (all lower-case) to send a POST request as opposed to the default GET. This works, but was not officially documented, so only use if you really need to.

Usage:
<pre>
this.ajaxcall( '/mygame/mygame/actMyAction.html', { lock: true,
arg1: myarg1,
arg2: myarg2
}, this, (result)=>{} );
</pre>

'''this.checkAction(action: string, nomessage?: boolean): boolean '''

Check if player can do the specified action by taking into account:
* if interface is locked it will return false and show message "An action is already in progress", unless nomessage set to true
* if player is not active it will return false and show message "This is not your turn", unless nomessage set to true
* if action is not in list in possible actions (defined by "possibleaction" in current game state) it will return false and show "This move is not authorized now" error (unconditionally).
* otherwise returns true
Example:
<pre>
function onClickOnGameElement( evt ) {
if( this.checkAction( "actMyAction" ) ) {
// Do the action
}
}
</pre>

'''this.checkPossibleActions(action: string): boolean'''

* this is independent of the player being active, so can be used instead of this.checkAction(). This is particularly useful for multiplayer states when the player is not active in a 'player may like to change their mind' scenario. Unlike this.checkAction, this function does NOT take interface locking into account

* if action is not in list in possible actions (defined by "possibleaction" in current game state) it will return false and show "This move is not authorized now" error (unconditionally).
* otherwise returns true

function onChangeMyMind( evt ) {
if( this.checkPossibleActions( "actMyAction" ) ) {
// Do the action
}
}

'''this.checkLock(nomessage?: boolean): boolean'''

When using "lock: true" in ajax call you can use this function to check if interface is in lock state (it will be locked during server call and notification processing).
This check can be used to block some other interactions which do not result in ajaxcall or if you want to suppress errors. Note: normally you only need to use this.checkAction(...), this is for advanced cases.

It will also show error unless nomessage is set to true

function onChangeMyMind( evt ) {
if( this.checkLock() ) {
// Do the action
}
}

== Notifications ==

When something happens on the server side, your game interface Javascript logic received a notification.
If you have not done so yet check what notification are in [[Main_game_logic:_yourgamename.game.php#Notifications]]

Here's how you can handle these notifications on the client side.

=== Subscribe to notifications ===

'''dojo.subscribe(notif_type: string, callback_obj: Object, handler: string|handler)'''
* notif_type - notification type/name send by php server
* callback_obj - usually this
* handler - if string method of callback_obj with name name is called, when notification is called, with notification object as parameter (see below)

Your Javascript "setupNotifications" method is the place where you can subscribe to notifications from your PHP code.

Here's how you associate one of your Javascript method to a notification "playDisc" (from Reversi example):

<pre>
setupNotifications: function() {
...
dojo.subscribe('playDisc', this, "notif_playDisc");
},
</pre>

Note: the "playDisc" corresponds to the name of the notification you define it in your PHP code, in your "notifyAllPlayers" or "notifyPlayer" method.

Then, you have to define your "notif_playDisc" method:

<pre>
notif_playDisc: function(notif) {
// Remove current possible moves (makes the board more clear)
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );
this.addDiscOnBoard( notif.args.x, notif.args.y, notif.args.player_id );
},
</pre>

In a notification handler like our "notif_playDisc" method, you can access all notifications arguments with "notif.args".

Example:

PHP

<pre>
$this->notifyAllPlayers( "apples", clienttranslate('player takes ${count} apples'), [ "count" => 3 ] );
</pre>

JavaScript

<pre>
setupNotifications: function() {
dojo.subscribe( 'apples', this, 'notif_apples' );
},

notif_apples: function(notif) {
//You can access the "count" like this:
alert("count = " + notif.args.count);
}
</pre>

=== The notification Object received by client ===

When sending a notification on your PHP, the client side will receive an Object with the following attributes:

* type - type of the notification (as passed by php function)
* log - the log string passed from php notification
* args - This is the arguments that you passed on your notification method on php
* bIsTableMsg - is true when you use [[Main_game_logic:_yourgamename.game.php#NotifyAllPlayers|NotifyAllPlayers]] method (false otherwise)
* channelorig - information about table ID (formatted as : "/table/t[TABLE_NUMBER]")
* gamenameorig - name of the game
* move_id - ID of the move associated with the notification
* table_id - ID of the table (comes as string)
* time - UNIX GMT timestamp
* uid - unique identifier of the notification
* h - unknown

'' Note that those information were inferred from observation on console log. If an Admin can confirm/correct (and remove this line), you're welcome :)''

=== Ignoring notifications ===

Sometimes you need to ignore some notification on client side. You don't want them to be shown in game log and you don't want them to be handled.

The most common use case is when a player gets private information. They will receive a specific notification (such as "You received Ace of Heart"), while other players would receive more generic notification ("Player received a card").

In X.game.php
<pre>
$this->notifyAllPlayers("dealCard", clienttranslate('${player_name} received a card'), [
'player_id' => $playerId,
'player_name' => $this->getActivePlayerName()
]);

$this->notifyPlayer($playerId, "dealCardPrivate", clienttranslate('You received ${cardName}'), [
"type" => $card["type"],
"cardName" => $this->getCardName($card["type"])
]);
</pre>

The problem with this approach is that the active player will receive two notifications:
* Player1 received a card
* You received Ace of Hearts

Hence, notification ignoring.

NOTE: You can think that it would be possible to send such notification to all players except active just by using notifyPlayer and it seems to work. The problem however is that table spectators would miss such notification and their user interface (and game log) wouldn't be updated. Since there is no way to send notification just to spectators, ignoring the notification (or "filtering") is the only reasonable solution.

'''setIgnoreNotificationCheck(notif_type: string, predicate: ((notif: Notif)=>boolean))'''
This method will set a check whether any of notifications of specific type should be ignored.

The parameters are:
* notif_type: type of the notification
* predicate (notif => boolean): a function that will receive notif object and will return true if this specific notification should be ignored

Before dispatching any notification of this type, the framework will call predicate to check whether notification should be ignored, if it return true - the notification will be dispatched, i.e. logged or handled.

<pre>
this.notifqueue.setIgnoreNotificationCheck( 'dealCard', (notif) => (notif.args.player_id == this.player_id) );
</pre>

IMPORTANT: Remember that this notification is ignored on the client side, but was still received by the client. Therefore it shouldn't contain any private information as cheaters can get it. In other words this is not a way to hide information.

IMPORTANT: When a game is reloaded with F5 or when opening a turn based game, old notifications are replayed as history notification. They are used just to update the game log and are stripped of all arguments except player_id, i18n and any argument present in message. If you use and other argument in your predicate you should '''preserve''' it as explained [[Main_game_logic:_yourgamename.game.php#Notify_players|here]].

=== Synchronous notifications ===

When several notifications are received by your game interface, these notifications are processed immediately, one after the other, in the same exact order they have been generated in your PHP game logic.

However, sometimes, you need to give some time to the players to figure out what happened on the game before jumping to the next notification. Indeed, in many games, there are a lot of automatic actions, and the computer is going to resolve all these actions very fast if you don't tell it not to do so.

As an example, for Reversi, when someone is playing a disc, we want to wait 500 milliseconds before doing anything else in order the opponent player can figure out what move has been played.

Here's how we do this, right after our subscription:
<pre>
dojo.subscribe( 'playDisc', this, "notif_playDisc" );
this.notifqueue.setSynchronous( 'playDisc', 500 ); // Wait 500 milliseconds after executing the playDisc handler
</pre>

-----

It is also possible to control the delay timing dynamically (e.g., using notification args). As an example, maybe your notification 'cardPlayed' should pause for a different amount of time depending on the number or type of cards played.

For this case, use '''setSynchronous''' without specifying the duration and use '''setSynchronousDuration''' within the notification callback.

* NOTE: If you forget to invoke '''setSynchronousDuration''', the game will remain paused forever!

<pre>
setupNotifications: function () {
dojo.subscribe( 'cardPlayed', this, 'notif_cardPlayed' );
this.notifqueue.setSynchronous( 'cardPlayed' ); // wait time is dynamic
...
},

notif_cardPlayed: function (notif) {
// MUST call setSynchronousDuration

// Example 1: From notification args (PHP)
this.notifqueue.setSynchronousDuration(notif.args.duration);
...

// Or, example 2: Match the duration to a Dojo animation
var anim = dojo.fx.combine([
...
]);
anim.play();
this.notifqueue.setSynchronousDuration(anim.duration);
},
</pre>

You can also manually call this.notifqueue.setSynchronousDuration(0) once client operations are finished, but be careful that even fast replay still has a path to call it.

'''WARNING: combining synchronous and ignored notifications'''
You must be careful when combining dynamic synchronous durations (as described above) with ignored notifications. If you have a conditionally ignored notification like this (see below section):

<pre>this.notifqueue.setIgnoreNotificationCheck( 'myNotif', (notif) => (notif.args.player_id == this.player_id) /* or any other condition */ )</pre>

then you CANNOT do

<pre>this.notifqueue.setSynchronous('myNotif');</pre>

as, when the ignored check passes, the notification handler, in which `this.notifqueue.setSychronousDuration` is called, is never called and so the duration is never set and interface locking results.

The workaround is to set a "dummy" time:

<pre>this.notifqueue.setSynchronous('myNotif', 5000);</pre>

whose value is irrelevant but must be large enough to cover the time before the notification handler is called. The large value never actually comes into play because the notification is either ignored, or the synchronous duration is reset to a sensible value inside the handler.

=== Pre-defined notification types ===

'''tableWindow''' - This defines notification to display [[Game_interface_logic:_yourgamename.js#Scoring_dialogs|Scoring Dialogs]], see below.

'''message''' - This defines notification that shows on players log and have no other effect (technically any unhandled notification will do the same but its recommended to use this keyword for consistency)

// You can call this on php side without doing anything on client side
self::notifyAllPlayers( 'message', clienttranslate('hello'), [] );

'''simplePause''' - This notification will just delay other notifications, maybe useful if you know you need some extra time for animation or something. Requires a time parameter.

<pre>
self::notifyAllPlayers( 'simplePause', '', [ 'time' => 500] ); // time is in milliseconds
</pre>

Note: the following types are RESERVED by framework, do not use:

gameStateChange gameStateChangePrivateArg gameStateMultipleActiveUpdate newActivePlayer playerstatus yourturnack clockalert tableInfosChanged playerEliminated tableDecision archivewaitingdelay end_archivewaitingdelay replaywaitingdelay end_replaywaitingdelay replayinitialwaitingdelay end_replayinitialwaitingdelay aiPlayerWaitingDelay replay_has_ended updateSpectatorList wouldlikethink updateReflexionTime undoRestorePoint resetInterfaceWithAllDatas zombieModeFail zombieModeFailWarning aiError skipTurnOfPlayer zombieBack allPlayersAreZombie gameResultNeutralized playerConcedeGame showTutorial showCursor showCursorClick skipTurnOfPlayerWarning banFromTable resultsAvailable switchToTurnbased newPrivateState infomsg

== Tooltips ==

=== Adding static tooltips ===

'''this.addTooltip(nodeId: string, helpStringTranslated: string, actionStringTranslated: string, delay?: number): void'''

Add a simple text tooltip to the DOM node.

Specify 'helpStringTranslated' to display some information about "what is this game element?".
Specify 'actionStringTranslated' to display some information about "what happens when I click on this element?".

You must specify both of the strings. You can only use one and specify an empty string ('') for the other one.

When you pass text directly function _() must be used for the text to be marked for translation! Except for empty string.

Parameter "delay" is optional. It is primarily used to specify a zero delay for some game element when the tooltip gives really important information for the game - but remember: no essential information must be placed in tooltips as they won't be displayed in some browsers (see [[BGA_Studio_Guidelines|Guidelines]]).

Example:
<pre>
this.addTooltip( 'cardcount', _('Number of cards in hand'), '' );
</pre>

Note: this generates static tooltip and attaches to existing dom element, if you need to generate tooltip more dynamically you have to call that method every time information about object is updated or use completely different tehnique, see dynamic tooltips below.

'''this.addTooltipHtml(nodeId: string, html: string, delay?: number): void'''

Add an HTML tooltip to the DOM node (for more elaborate content such as presenting a bigger version of a card).

'''this.addTooltipToClass(cssClass: string, helpStringTranslated: string, actionStringTranslated: string, delay?: number ): void'''

Add a simple text tooltip to all the DOM nodes set with this cssClass. See more details above for this.addTooltip.
this.addTooltipToClass( 'meeple', _('This is A Meeple'), _('Click to tickle') );

IMPORTANT: all concerned nodes must exist and have IDs to get tooltips.

'''this.addTooltipHtmlToClass(cssClass: string, html: string, delay?: number): void'''

Add an HTML tooltip to to all the DOM nodes set with this cssClass (for more elaborate content such as presenting a bigger version of a card).

IMPORTANT: all concerned nodes must exist and have IDs to get tooltips.

=== Removing static tooltips ===

'''this.removeTooltip(nodeId: string): void'''

Remove a tooltip from the DOM node with given id.

=== Advanced tooltips ===

'''force tooltip to open'''

If you want to force tooltip to open in reaction to some other action, i.e. click you can do this

this.tooltips[id].open(id)

where id is the id of the tooltip node where tooltip was installed.

'''dynamic tooltips'''

See [[BGA_Studio_Cookbook#Dynamic_tooltips]]

'''tooltips on mobile'''

Tooltips is very unreliable on mobile, it is recommended to implement some other method to obtaining same information,
such as simple click handler in dedicated "Help" mode or provide dedicated clickable areas such as corner of card.

== Warning messages ==

Sometimes, there is something important that is happening in the game and you have to make sure all players get the message. Most of the time, the evolution of the game situation or the game log is enough, but sometimes you need something more visible.

Ex: someone fulfills one of the end of the game conditions, so this is the last turn.

'''this.showMessage(msg: string, type: string): void'''

showMessage shows a message in a big rectangular area on the top of the screen of the current player, and it dissapears after few seconds (also it will be in the log in some cases).

* "msg" is the string to display. It should be translated.
* "type" can be set to "info", "error", "only_to_log" or custom string. If set to "info", the message will be an informative message on a white background. If set to "error", the message will be an error message on a red background and it will be added to log. If set to "only_to_log", the message will be added to the game log but will not popup at the top of the screen.
If set to custom string, it will be transparent, to use custom type define "head_xxx" in css, where xxx is the type. For example if you want yellow warning, use "warning" as type and add this to css:
.head_warning {
background-color: #e6c66e;
}

Important: the normal way to inform players about the progression of the game is the game log. The "showMessage" is intrusive and should not be used often.

<pre>
notif_messageinfo: function(notif) {
if (!g_archive_mode) {
var message = this.format_string_recursive(notif.log, notif.args);
this.showMessage(_('Announcement:') + " " + message, 'info');
}
},
</pre>

Show message could be used on the client side to prevent user wrong moves before it is send to server.
Example from 'battleship':
<pre>
onGrid: function(event) {
if (checkIfPlayerTriesToFireOnThemselves(event)) {
this.showMessage(_('This is your own board silly!'), 'error');
return;
}
...
},
</pre>

'''this.showMoveUnauthorized(): void'''

Shows predefined user error that move is unauthorized now

<pre>
onPet: function(event) {
if (checkPet(event)==false) {
this.showMoveUnauthorized();
return;
}
...
},
</pre>

== Dialogs ==

=== Confirmation dialog ===

When an important action with a lot of consequences is triggered by the player, you may want to propose a confirmation dialog.

CAREFUL: the general guideline of BGA is to AVOID the use of confirmation dialogs. Confirmation dialogs slow down the game and bother players. The players know that they have to pay attention to each move when they are playing online.

The situations where you should use a confirmation dialog are the following:
* It must not happen very often during a game.
* It must be linked to an action that can really "kill a game" if the player does not pay attention.
* It must be something that can be done by mistake (ex: a link on the action status bar).

'''this.confirmationDialog(message: string, yesHandler: (param: any) => void, noHandler?: (param: any) => void, param?: any): void'''

* message - message will be shown to user, use _() to translate
* yesHandler - non-optional handler to be called on yes
* noHandler - optional handler to called on no
* param - if specified, it will be passed to both handlers
NOTE: this is async function, it does not return anything and you should not do anything after, you must do everything in handlers

How to display a confirmation dialog:
<pre>
this.confirmationDialog(_("Are you sure you want to bake a pie?"), () => {
this.bakeThePie();
});
return; // nothing should be called or done after calling this, all action must be done in the handler
</pre>
With param and both handlers
<pre>
this.confirmationDialog(_("Are you sure you want to bake a pie?"),
(ingredient) => this.bakeThePie(ingredient),
(ingredient) => console.log(`cancelled baking of ${ingredient}`),
'apple');
</pre>

=== Multiple choice dialog ===

You can use this dialog to give user a choice with small amount of options

'''this.multipleChoiceDialog(message: string, choices: string[], callback: (choice: number) => void): void'''
* message - message will be shown to user, use _() to translate
* choices - array of choices
* callback - non-optional handler to be called on choice made, the choice parameter is the INDEX of the choice from the array of choices

NOTE: this is async function, it does not return anything and you should not do anything after, you must do everything in handlers
NOTE: there is no cancel handler, so make sure you gave user a choice to get out of it

Example:
<pre>
const keys = ["0", "1", "5", "10"];
this.multipleChoiceDialog(_("How many bugs to fix?"), keys, (choice) => {
if (choice==0) return; // cancel operation, do not call server action
var bugchoice = keys[choice]; // choice will be 0,1,2,3 here
this.bgaPerformAction("fixBugs", { number: bugchoice });
});
return; // must return here
</pre>

=== Generic Dialogs ===

As a general rule, you shouldn't use dialogs windows.

BGA guidelines specify that all game elements should be displayed on the main screen. Players can eventually scroll down to see game elements they don't need to see anytime, and you may eventually create anchors to move between game area section. Of course dialogs windows are very practical, but the thing is: all players know how to scroll down, and not all players know how to show up your dialog window. In addition, when the dialog shows up, players can't access the other game components.

Sometimes although, you need to display a dialog window. Here is how you do this:

// Create the new dialog over the play zone. You should store the handler in a member variable to access it later
this.myDlg = new ebg.popindialog();
this.myDlg.create( 'myDialogUniqueId' );
this.myDlg.setTitle( _("my dialog title to translate") );
this.myDlg.setMaxWidth( 500 ); // Optional

// Create the HTML of my dialog.
// The best practice here is to use [[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl#Javascript_templates|Javascript templates]]
var html = this.format_block( 'jstpl_myDialogTemplate', {
arg1: myArg1,
arg2: myArg2,
...
} );

// Show the dialog
this.myDlg.setContent( html ); // Must be set before calling show() so that the size of the content is defined before positioning the dialog
this.myDlg.show();

// Now that the dialog has been displayed, you can connect your method to some dialog elements
// Example, if you have an "OK" button in the HTML of your dialog:
dojo.connect($('my_ok_button'), 'onclick', this, (event) => {
event.preventDefault();
this.myDlg.destroy();
});

If necessary, you can remove the default top right corner 'close' icon, or replace the function called when it is clicked:
// Removes the default close icon
this.myDlg.hideCloseIcon();

// Replace the function call when it's clicked
this.myDlg.replaceCloseCallback((event) => { ... });

=== Scoring dialogs ===

Sometimes at the end of a round you want to display a big table that details the points wins in each section of the game.

Example: in Hearts game, we display at the end of each round the number of "heart" cards collected by each player, the player who collected the Queen of Spades, and the total number of points loose by each player.

Scoring dialogs are managed entirely on '''PHP side''', but they are described here as their effects are visible only on client side.

Displaying a scoring dialog is quite simple and is using a special notification type: "tableWindow":
<pre>
// on PHP side:
$this->notifyAllPlayers( "tableWindow", '', array(
"id" => 'finalScoring',
"title" => clienttranslate("Title of the scoring dialog"),
"table" => $table
));
</pre>

The "table" argument is a 2 dimensional PHP array that describes the table you want to display, line by line and column by column.

Example: display an 3x3 array of strings
<pre>
$table = [
[ "one", "two", "three" ], // This is my first line
[ "four", "five", "six" ], // This is my second line
[ "seven", "height", "nine" ] // This is my third line
];
</pre>

As you can see above, in each "cell" of your array you can display a simple string value. But you can also display a complex value with a template and associated arguments like this:
<pre>
$table = [
[ "one", "two", [ "str" => clienttranslate("a string with an ${argument}"), "args" => [ 'argument' => 'argument_value' ] ] ],
[ "four", "five", "six" ],
[ "seven", "height", "nine" ]
];
</pre>

This is especially useful when you want to display player names with colors. Example from "Hearts":
<pre>
$firstRow = [ '' ];
foreach( $players as $player_id => $player ) {
$cell = [ 'str' => '${player_name}',
'args' => [ 'player_name' => $player['player_name'] ],
'type' => 'header'
];
$firstRow[] = $cell;
}
$table[] = $firstRow;
...
</pre>

You can also use three extra attributes in the parameter array for the notification:
* '''header''': the content for this parameter displays before the table (also, the html will be parsed and player names will be colored according to the current game colors).
* '''footer''': the content for this parameter displays after the table (no parsing for coloring the player names)
* '''closing''': if this parameter is used, a button will be displayed with this label at the bottom of the popup and will allow players to close it (more easily than by clicking the top right 'cross' icon).

<pre>
$this->notifyAllPlayers( "tableWindow", '', [
"id" => 'finalScoring',
"title" => clienttranslate("Title of the scoring dialog"),
"table" => $table,
"header" => ['str' => clienttranslate('Table header with parameter ${number}'),
'args' => [ 'number' => 3 ],
],
"footer" => '<div class="myfoot"></div>',
"closing" => clienttranslate( "Closing button label" )
] );
</pre>

Note: currently id is not used - so you cannot access resulting div by id on js side
Note: any traslatable stirng have to be wrapped by clienttranslate() on top level OR it has to be recursive template.

DO NOT DO THIS:
<pre>
"footer" => '<div>'.clienttranslate( "The end" ).'</div>', // this will not work for translations!!!
</pre>

=== Scoring animated display ===

Sometimes, you may want to display a score value over an element to make the scoring easier to follow for the players (Terra Mystica final scoring for example).
You can do it with:

'''this.displayScoring(anchor_id: string, color: string, score: number | string, duration?: number, offset_x?: number, offset_y?: number): void'''

'''anchor_id''': ID of the html element to place the animated score onto (without the '#')

'''color''': hexadecimal RGB representation of the color (should be the color of the scoring player), but without a leading '#'. For instance, 'ff0000' for red.

'''score''': numeric score to display, prefixed by a '+' or '-'

'''duration''': animation duration in milliseconds (optional, default is 1000)

'''offset_x''' and '''offset_y''': if both offset_x and offset_y are defined and not null, apply the following offset (in pixels) to the scoring animation.
Note that the score is centered in the anchor, so the offsets might have to be negative if you calculate the position.

Note: if you want to display successively each score, you can use ''this.notifqueue.setSynchronous()'' function.
<pre>
setupNotifications: function() {
dojo.subscribe( 'displayScoring', this, "notif_displayScoring" );
...
}
...

notif_displayScoring: function(notif) {
const duration = notif.args.duration?notif.args.duration:1000;
this.notifqueue.setSynchronous('displayScoring', duration );
this.displayScoring( notif.args.target, notif.args.color, notif.args.score, duration);
},
</pre>

=== Speech bubble ===

For better interactivity in some games (Love Letter for example), you may use comic book style speech bubbles to express the players voices.
This is done with showBubble:

'''this.showBubble(anchor_id: string, text: string, delay?: number, duration?: number, custom_class?: string): void'''

* anchor_id - where to attach the bubble
* text - what to put in bubble, can be html
* delay - delay in milliseconds (optional, default 0)
* duration - duration of animation in milliseconds (optional, default 3000)
* custom_class - extra class to add to bubble (optional), if you need to override the default bubble style

<pre>
this.showBubble('meeple_2', _('Hello'), 0, 1000, 'pink_bubble');
</pre>

<pre>
notif_speechBubble(notif) {
var html = this.format_string_recursive(notif.args.text, notif.args.args);
this.showBubble(notif.args.target, html, notif.args.delay ?? 0, notif.args.duration ?? 1000);
},
</pre>

'''Warning''': if your bubble could overlap other active elements of the interface (buttons in particular), as it stays in place even after disappearing, you should use a custom class to give it the style "pointer-events: none;" in order to intercept click events.

Note: If you want this visually, but want to take complete control over this bubble and its animation (for example to make it permanent) you can just use div with 'discussion_bubble' class on it, and content of div is what will be shown.

== Translations ==

See [[Translations]]

== Players panels ==

=== Update players score ===

The column player_score from the player table is automatically loaded into this.scoreCtrl and therefore into the stars location on the player board. This occurs sometime after the game setup() function. However this score must be updated as the game progresses using notifications.

Note: this.scoreCtrl[player_id] is object of class [[Counter]], you can use other counter API.

Increase a player score (with a positive or negative number):

<pre>
this.scoreCtrl[ player_id ].incValue( score_delta );
</pre>

Set a player score to a specific value:

<pre>
this.scoreCtrl[ player_id ].setValue( new_score );
</pre>

Set a player score to a specific value with animation:

<pre>
this.scoreCtrl[ player_id ].toValue( new_score );
</pre>

Typical usage would be (that will process 'score' notification):
<pre>
setupNotifications : function() {
...
dojo.subscribe('score', this, "notif_score");
},
notif_score: function(notif) {
this.scoreCtrl[notif.args.player_id].setValue(notif.args.player_score);
},
</pre>

=== Adding stuff to player's panel ===

At first, create a new "JS template" string in your template (tpl) file:

(from Gomoku example)
<pre>
var jstpl_player_board = '\<div class="cp_board">\
<div id="stoneicon_p${id}" class="gmk_stoneicon gmk_stoneicon_${color}"></div><span id="stonecount_p${id}">0</span>\
</div>';
</pre>

Then, you add this piece of code in your JS file to add this template to each player panel:

<pre>
// Setting up player boards
for( var player_id in gamedatas.players )
{
var player = gamedatas.players[player_id];

// Setting up players boards if needed
var player_board_div = $('player_board_'+player_id);
dojo.place( this.format_block('jstpl_player_board', player ), player_board_div );
}
</pre>

(Note: the code above is of course from your "setup" function in your Javascript).

Very often, you have to distinguish current player and others players. In this case, you just have to create another JS template (ex: jstpl_otherplayer_board) and use it when "player_id" is different than "this.player_id".

=== Fixing Player Panel heights ===

You may find that the player panels don't automatically resize when adding something to (or removing something from) a player panel while the display is in portrait mode (i.e. the player summary panels are at the top of the screen rather than down the right side).

When this happens, call <pre>this.adaptPlayersPanels();</pre> This recalculates the layout and also adjusts the position of the actionbar for you.

=== Player's panel disabling/enabling ===

'''this.disablePlayerPanel(player_id: number): void'''

Disable given player panel (the panel background become gray).

Usually, this is used to signal that this played passes, or will be inactive during a while.

Note that the only effect of this is visual. There are no consequences on the behaviour of the panel itself.

'''this.enablePlayerPanel(player_id:number): void'''

Enable a player panel that has been disabled before.

'''this.enableAllPlayerPanels(): void'''

Enable all player panels that has been disabled before.

=== Player order ===

'''this.updatePlayerOrdering(): void'''

This function makes sure that player order in player's panel matches this.gamedatas.playerorder and its normally called by framework.
You can call it yoursel if you change this.gamedatas.playerorder from notification.
Also you can override this function to change defaults OR insert a non-player panel [[BGA_Studio_Cookbook#Inserting_non-player_panel]].

=== Counters ===
Note: there is bga component called "ebg/counter" this API is not using it, these methods
below declared right in core game. If you need animation for counters use ebg/counter

To use this API just create a counter dom element like this (class does not really matter)
<pre>
<div class="counter" id="bread"></div>
<div class="counter" id="coin"></div>
</pre>
The "bread" will the counter name.

The php code should send all "counters" data from getAllDatas() method like this

game.php
<pre>
protected function getAllDatas() {
// (the key must match counter_name)
$result['counters']=[
'bread' => [
'counter_name' => 'bread',
'counter_value' => 3
],
'coin' => [
'counter_name' => 'coin',
'counter_value' => 5
]
];
return $result;
}
</pre>

'''setCounter(counter_name: stirng, new_value: string | number): void'''

updates the global this.gamedatas.counters and value of node $(counter_name)
<pre>
notif_counter: function(notif) {
this.setCounter(notif.args.counter_name, notif.args.counter_value);
},
</pre>

'''incCounter(counter_name: string, delta: number): void'''
<pre>
notif_counter : function(notif) {
this.incCounter(notif.args.counter_name, notif.args.inc);
},
</pre>

'''updateCounters(counters: object): void'''

Useful for updating game counters in the player panel (such as resources).
'counters' arg is map of counters (the key must match counter_name)
{
'bread': {
'counter_name' : 'bread',
'counter_value' => 3
},
'coin': {
'counter_name' : 'coin',
'counter_value' => 5
}
}
All counters MUST be referenced in this.gamedatas.counters (means they should be send from php) and will be updated.
DOM objects referenced by 'counter_name' will have their innerHTML updated with 'counter_value'.

Usually you call this from notification

<pre>
notif_counter : function(notif) {
this.updateCounters(notif.args.counters);
},
</pre>

== BGA GUI components ==

BGA framework provides some useful ready-to-use components for the game interface:

[[Studio#BGA_Studio_game_components_reference]]

Note that each time you are using an additional component, you must declare it at the top of your Javascript file in the list of modules used.

Example if you are using "ebg.stock":
<pre>
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/stock" /// <=== we are using ebg.stock module
],
</pre>

== BGA Buttons ==

=== Basic Button ===

'''this.addActionButton(id: string, label: string, method: string | eventhandler, destination?: string, blinking?: boolean, color?: string): void'''

You can use this method to add an action button in the main action status bar (or other places).

Arguments:
* id: an element ID that should be unique in your HTML DOM document.
* label: the text of the button. Should be translatable (use _() function). Note: this can also be any html, such as "<div class='brick'></div>", see example below on how to make image action buttons.
* method: the name of your method that must be triggered when the player clicks on this button (can be name of the method on game class or handler).
* destination (optional): id of parent on where to add button, ONLY use in rare cases if location is not action bar. Use '''null''' as value if you need to specify other arguments.
* blinking (optional): if set to '''true''', the button is going blink to catch player's attention. Please DO NOT abuse blinking button. If you need button to blink after some time passed add class 'blinking' to the button later.
* color: could be '''blue''' (default), '''red''','''gray''' or '''none'''.

You should only use this method in your "onUpdateActionButtons" method. Usually, you use it like this:

<pre>
onUpdateActionButtons: function( stateName, args ) {
if (this.isCurrentPlayerActive()) {
switch( stateName ) {
case 'giveCards':
this.addActionButton( 'giveCards_button', _('Give selected cards'), 'onGiveCards' );
this.addActionButton( 'pass_button', _('Pass'), () => this.bgaPerformAction('actPass') );
break;
}
}
},
</pre>

In the example above, we are adding a "Give selected cards" button in the case we are on game state "giveCards". When player clicks on this button, it triggers our "onGiveCards" method.

Example using blinking red button:
<pre>
this.addActionButton( 'button_confirm', _('Confirm?'), 'onConfirm', null, true, 'red');
</pre>

If you want to call the handler with arguments, you can use arrow functions, like this:
<pre>
this.addActionButton( 'commit_button', _('Confirm'), () => this.onConfirm(this.selectedCardId), null, false, 'red');
</pre>

=== Image Button ===

You can use the same method, but add extra class to a button to disable the padding and style it, i.e.
<pre>
this.addActionButton( 'button_brick', '<div class="brick"></div>', ()=>{... on brick ...}, null, null, 'gray');
dojo.addClass('button_brick','bgaimagebutton');
</pre>

where

<pre>
.bgaimagebutton {
padding: 0px 12px;
min-height: 28px;
border: none;
}
</pre>

If you use this a lot, you can define a helper function, i.e.
<pre>
/**
* This method can be used instead of addActionButton, to add a button which is an image (i.e. resource). Can be useful when player
* need to make a choice of resources or tokens.
*/
addImageActionButton: function(id, div, handler, bcolor, tooltip) {
if (typeof bcolor == "undefined") {
bcolor = "gray";
}
// this will actually make a transparent button id color = gray
this.addActionButton(id, div, handler, null, false, bcolor);
// remove border, for images it better without
dojo.style(id, "border", "none");
// but add shadow style (box-shadow, see css)
dojo.addClass(id, "shadow bgaimagebutton");
// you can also add additional styles, such as background
if (tooltip) {
dojo.attr(id, "title", tooltip);
}
return $(id);
},
</pre>

=== Disabling Button ===

You can disable the '''bgabutton''' by adding the css class '''disabled''' in you js. The disabled button is still visible but is grey and not clickable.
For example in the '''onUpdateActionButtons''' :
<pre>
this.addActionButton('play_button_id', _('Play 1 to 3 cards'), 'playFunctionButton');
if (condition) {
dojo.addClass('play_button_id', 'disabled');
}
</pre>

=== Custom Buttons ===

You can create a custom button, but the BGA framework provides a standard button that requires only .css classes: '''bgabutton''' and '''bgabutton_${color}'''.

'''Examples:'''

<pre>
<a href="#" id="my_button_id" class="bgabutton bgabutton_blue"><span>My blue button</span></a>

<a href="#" id="my_button_id" class="bgabutton bgabutton_red bgabutton_big"><span>My big red button</span></a>
</pre>

'''Note''': To see it in action, check out ''Coloretto''.

=== Button outside of action bar ===

Use addActionButton() method with destination argument set
<pre>
this.addActionButton( 'commit_button', _('Confirm'), 'onConfirm', 'player_board', true, 'red');
</pre>

in example above the button will be place on object with id 'player_board'

== Image loading ==

See also [[Game_art:_img_directory]].

'''Be careful''': by default, ALL images of your img directory are loaded on a player's browser when he loads the game. For this reason, don't let in your img directory images that are not useful, otherwise it's going to slowdown the game load.

'''this.dontPreloadImage(image_file_name: string)'''

Using dontPreloadImage, you tell the interface to not preload a specific image in your img directory.

Example of use:
<pre>
this.dontPreloadImage( 'cards.png' );
</pre>

This is particularly useful if for example you have 2 different themes for a game. To accelerate the loading of the game, you can specify to not preload images corresponding to the other theme.

Another example of use: in "Gosu" game with Kamakor extension, you play with 5 sets of cards among 10 available. Cards images are organized by sets, and we only preload the images corresponding to the 5 current sets with '''ensureSpecificGameImageLoading( image_file_names_array )'''.
<pre>
// By default, do not preload anything
this.dontPreloadImage( 'cards.png' );
this.dontPreloadImage( 'clan1.png' );
this.dontPreloadImage( 'clan2.png' );
this.dontPreloadImage( 'clan3.png' );
this.dontPreloadImage( 'clan4.png' );
this.dontPreloadImage( 'clan5.png' );
this.dontPreloadImage( 'clan6.png' );
this.dontPreloadImage( 'clan7.png' );
this.dontPreloadImage( 'clan8.png' );
this.dontPreloadImage( 'clan9.png' );
this.dontPreloadImage( 'clan10.png' );
var to_preload = [];
for( i in this.gamedatas.clans )
{
var clan_id = this.gamedatas.clans[i];
to_preload.push( 'clan'+clan_id+'.png' );
}

this.ensureSpecificGameImageLoading( to_preload );

</pre>

'''Note:''' You don't need to specify to not preload game box images (game_box.png, game_box75.png...) since they are not preloaded by default.

'''this.ensureSpecificGameImageLoading(list: string[])'''

This is oppostive of dontPreloadImage - its ensure specific images is loaded. Note: only makes sense if preload list is empty, otherwise everything is loaded anyway

'''load specific images'''
All images that will be preloaded stored in g_img_preload. If you want to override it directly - there is no API, but you can do this in GAME constructor

g_img_preload = ['tokens.png', 'trains.png', 'loc_plan.png', 'eng.png', 'eng-back.png'];

You can also set it to empty array and call ensureSpecificGameImageLoading() on specific images

== Sounds ==

Add a custom sound and make it load with your interface:

Add this in your template (.tpl) file:
<pre>
<audio id="audiosrc_<gamename>_<yoursoundname>" src="{GAMETHEMEURL}img/<gamename>_<yoursoundname>.mp3" preload="none" autobuffer></audio>
<audio id="audiosrc_o_<gamename>_<yoursoundname>" src="{GAMETHEMEURL}img/<gamename>_<yoursoundname>.ogg" preload="none" autobuffer></audio>
</pre>

Note: this is a requirement to provide both a mp3 and a ogg file with the names <code><gamename>_<yoursoundname>[.ogg][.mp3]</code>.

Play the sound (from your .js file):

<pre>
playSound('<gamename>_<yoursoundname>'); // do not add 'this.' - its a global function
</pre>

Disable the standard "move" sound for this move (to replace it with your custom sound):

Add this to your notification handler:

<pre>
this.disableNextMoveSound();
</pre>

Note: it only disable the sound for the next move.

== Title bar and states ==

=== Client states ===

Client states is a way to simulate the state transition but without actually going
to server. It is usefull when you need to ask user multiple questions before you
send things to server

'''this.setClientState(newState: string, args: object)'''

Example:
this.setClientState("client_playerPicksLocation", {
descriptionmyturn : _("${you} must select location"),
});

For more information see [[BGA_Studio_Cookbook#Multi_Step_Interactions:_Select_Worker.2FPlace_Worker_-_Using_Client_States]]

'''this.restoreServerGameState()'''
If you are in client state it will restore the current server state (cheap undo)

'''this.on_client_state'''
Boolean indicating that we are in client state

=== Title bar ===
If you simply want to show something in title bar you can do it directly
$('pagemaintitletext').innerHTML = text;

This however will not work with parameters and will not draw You in color,
if you want to do proper args rendering use method below

;'''this.removeActionButtons()'''
Removes all buttons from title bar

;'''this.updatePageTitle()'''
:This function allows to update the current page title and turn description according to the game state arguments. If the current game state description this.gamedatas.gamestate.descriptionmyturn is modified before calling this function it allows to update the turn description without changing state. This will handle arguments substitutions properly.

Note: this functional also will calls this.onUpdateActionButtons, if you want different buttons then state defaults, use method in example to replace them, if it becomes too clumsy use client states (see above)

Example from Terra Mystica:
<pre>
onClickFavorTile: function( evt ) {
...
if ( ... ) {
this.gamedatas.gamestate.descriptionmyturn = _('Special action: ') + _('Advance 1 space on a Cult track');
this.updatePageTitle();
this.removeActionButtons();
this.addActionButton( ... );
...
return;
}
...

}
</pre>

== User preferences ==
'''this.getGameUserPreference(pref_id)'''

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

'''this.setGameUserPreference(pref_id, value)'''

Programmatically change a user preference. It will have the same effect as if the player changed the value in the select combo box, in the top-right menu.

'''this.onGameUserPreferenceChanged'''

A callback you can define if you want to be notified when a user changes a user preference.

Example:<pre>
onGameUserPreferenceChanged: function(pref_id, pref_value) {
switch (pref_id) {
case 201:
document.getElementsByTagName('html')[0].classList.toggle('dark-background', pref_value == 2);
break;
}
}
</pre>

== Other useful stuff ==

'''dojo.hitch'''

With dojo.hitch, you can create a callback function that will run with your game object context whatever happen.

Typical example: display a BGA confirmation dialog with a callback function created with dojo.hitch:

<pre>
this.confirmationDialog( _('Are you sure you want to make this?'), dojo.hitch( this, function() {
this.bgaPerformAction('makeThis');
} ) );
</pre>

In the example above, using dojo.hitch, we ensure that the "this" object will be set when the callback is called.

NOTE: In modern JS there are lambdas that eliminate need for that, the example above will look like this
<pre>
this.confirmationDialog( _('Are you sure you want to make this?'), () => this.bgaPerformAction( 'makeThis') );
</pre>

;'''onScreenWidthChange()'''
:This function can be overridden in your game to manage some resizing on the client side when the browser window is resized. This function is also triggered at load time, so it can be used to adapt to the :viewport size at the start of the game too.

; this.bRealtime
: Return true if the game is in realtime. Note that having a distinct behavior in realtime and turn-based should be exceptional.

; g_replayFrom
: Global contains replay number in live game, it is set to undefined (i.e. not set) when it is not a replay mode, so consequentially the good check is '''typeof g_replayFrom != 'undefined'''' which returns true if the game is in replay mode <i>during the game</i> (the game is ongoing but the user clicked "replay from this move" in the log)

; g_archive_mode
: Returns true if the game is in archive mode <i>after the game</i> (the game has ended)

; this.instantaneousMode
: Returns true during replay/archive mode if animations should be skipped. Only needed if you are doing custom animations. (The BGA-provided animation functions like <i>this.slideToObject()</i> automatically handle instantaneous mode.)
: Technically, when you click "replay from move #20", the system replays the game from the very beginning with moves 0 - 19 happening in instantaneous mode and moves 20+ happening in normal mode.

; g_tutorialwritten
: Returns an object like the below if the game is in tutorial mode, or undefined otherwise. Tutorial mode is a special case of archive mode where comments have been added to a previous game to teach new players the rules.
{
author: "91577332",
id: "576",
mode: "view"
status: "alpha"
version_override: null
viewer_id: "84554161"
}

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

[[Category:Studio]]

Game interface logic: Game.js

2024-09-25T17:54:43Z

Sguzzer Gunayer: /* Connecting */

{{Studio_Framework_Navigation}}

__TOC__

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

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

== File structure ==

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

Here is the basic structure:

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

More details:

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

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

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

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

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

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

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

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

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

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

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

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

== Dojo framework ==

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

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

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

== Javascript minimization (after July 2020) ==

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

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

== Accessing Players Information ==

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

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

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

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

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

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

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

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

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

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

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

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

== Accessing and manipulating the DOM ==

=== Element by Id ===

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

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

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

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

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

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

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

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

=== Style ===

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

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

Examples:

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

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

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

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

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

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

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

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

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

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

=== Classes ===

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

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

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

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

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

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

Example from ''Reversi'':

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

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

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

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

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

'''Vanilla JS classList'''

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

=== Attributes ===

;dojo.attr

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

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

'''Vanilla JS attr'''

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

=== Queries ===

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

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

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

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

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

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

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

'''Vanilla JS query'''

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

=== Creating and Destroying elements ===

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

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

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

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

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

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

Create element

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

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

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

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

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

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

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

const div = ``;
'''this.format_string_recursive'''

This bga function is similar to this.format_string but is capable of processing recursive argument structures and translations. It is used to format server notifications.

TODO: find better place for these function docs

=== Moving elements ===

'''dojo.place(node: string | Element, refNode: ElementOrId, pos?: string | number): Element'''

dojo.place is the best function to insert HTML code somewhere in your game interface without breaking something. It is much better to use than the '''innerHTML=''' method if you must insert HTML tags and not only values.

node: can be a string or a DOM node. If it is a string starting with “<”, it is assumed to be an HTML fragment, which will be created. Otherwise it is assumed to be an id of a DOM node.

<pre>
// Insert your HTML code as a child of a container element
dojo.place( "<div class='foo'></div>", "your_container_element_id" );
</pre>

pos: optional argument. Can be a number or one of the following strings: “before”, “after”, “replace”, “only”, “first”, or “last”. If omitted, “last” is assumed.

* "replace": replace the container element with my_node element
* "first": places the node as a child of the reference node. The node is placed as the first child.
* "last" (default): places the node as a child of the reference node. The node is placed as the last child.
* "before": places the node right before the reference node.
* "after": places the node right after the reference node.
* "only": replaces all children of the reference node with the node.

this parameter can be a positive integer. In this case, the node will be placed as a child of the reference node with this number (counting from 0). If the number is more than number of children, the node will be appended to the reference node making it the last child.

<pre>
// Replace all children of container with my_node
dojo.place( $('my_node'), "your_container_element_id", "only" );
</pre>

See also full doc on dojo.place: [https://dojotoolkit.org/reference-guide/1.7/dojo/place.html]

Usually, when you want to insert some piece of HTML in your game interface, you should use "[[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl#Javascript_templates|Javascript templates]]".

But you can also relocate elements like that. Note: it won't animate if you do that.

'''this.placeOnObject(mobile_obj: ElementOrId, target_obj: ElementOrId): void'''

places mobile_obj on target_obj, set the absolute positions and centers the mobile_obj on target_obj,
effect is immediate

This is not really an animation, but placeOnObject is frequently used before starting an animation.

Example:
<pre>
// (We just created an object "my_new_token")

// Place the new token on current player board
this.placeOnObject( "my_new_token", "overall_player_board_"+this.player_id );

// Then slide it to its position on the board
this.slideToObject( "my_new_token", "a_place_on_board" ).play();
</pre>

'''this.placeOnObjectPos(mobile_obj: ElementOrId, target_obj: ElementOrId, target_x: number, target_y: number): void'''

This method works exactly like placeOnObject, except than you can specify some (x,y) coordinates (in px). This way, the center of "mobile_obj" will be placed to the specified x,y position relatively to the center of "target_obj".

''Note: the placement works differently from this.slideToObjectPos'', since coordinates are calculated based on the center of objects.

'''this.attachToNewParent(mobile_obj: ElementOrId, target_obj: ElementOrId): void'''

With this method, you change the HTML parent of "mobile_obj" element without moving it.
"target_obj" is the new parent of this element. The beauty of
attachToNewParent is that the mobile_obj element DOES NOT MOVE during this process.

What happens is that the method calculate a relative position of mobile_obj to make sure it does not move after the HTML parent changes.

Why using this method?

Changing the HTML parent of an element can be useful for the following reasons:
* When the HTML parent moves, all its child are moving with them. If some game elements is no more linked with a parent HTML object, you may want to attach it to another place.
* The z_order (vertical order of display) depends on the position in the DOM, so you may need to change the parent of some game elements when they are moving in your game area.

'''CAREFUL''': this function destroys original object and places a clone onto a new parent, this will break all references to this HTML element (ex: dojo.connect).
If you need version that does not destroy the object but the same otherwise see [[BGA_Studio_Cookbook#Attach_to_new_parent_without_destroying_the_object]]

== Animations ==

===Dojo Animations===

BGA animations is based on Dojo Animation ([http://dojotoolkit.org/documentation/tutorials/1.8/animation/ see tutorial here]).

However, most of the time, you can just use methods below, which are built on top of Dojo Animation.

Note: one interesting method from Dojo that could be useful from time to time is "Dojo.Animation". It allows you to make any CSS property "slide" from one value to another.

Note 2: the slideTo methods are not compatible with CSS transform (scale, zoom, rotate...). If possible, avoid using CSS transform on nodes that are being slided. Eventually, the only possible solution to make these 2 compatible is to disable all CSS transform properties, use slideToObjectPos/placeOnObjectPos, and then apply them again.

===Sliding===

'''this.slideToObject(mobile_obj: ElementOrId, target_obj: ElementOrId, duration?: number, delay?: number): Animation'''

You can use slideToObject to "slide" an element to a target position.

Sliding element on the game area is the recommended and the most used way to animate your game interface. Using slides allow players to figure out what is happening on the game, as if they were playing with the real boardgame.

The parameters are:
* mobile_obj: the ID of the object to move. This object must be "relative" or "absolute" positioned.
* target_obj: the ID of the target object. This object must be "relative" or "absolute" positioned. Note that it is not mandatory that mobile_obj and target_obj have the same size. If their size are different, the system slides the center of mobile_obj to the center of target_obj.
* duration: (optional) defines the duration in millisecond of the slide. The default is 500 milliseconds.
* delay: (optional). If you defines a delay, the slide will start only after this delay. This is particularly useful when you want to slide several object from the same position to the same position: you can give a 0ms delay to the first object, a 100ms delay to the second one, a 200ms delay to the third one, ... this way they won't be superposed during the slide.

BE CAREFUL: The method returns an dojo.fx animation, so you can combine it with other animation if you want to. It means that you have to call the "play()" method, otherwise the animation WON'T START.

Example:
<pre>
this.slideToObject( "some_token", "some_place_on_board" ).play();
</pre>

'''this.slideToObjectPos(mobile_obj: ElementOrId, target_obj: ElementOrId, target_x: number, target_y: number, duration?: number, delay?: number): Animation'''

This method does exactly the same as "slideToObject", except than you can specify some (x,y) coordinates. This way, "mobile_obj" will slide to the specified x,y position relatively to "target_obj".

Example: slide a token to some place on the board, 10 pixels from the top:
<pre>
this.slideToObjectPos( "some_token", "some_place_on_board", 0, 10 ).play();
</pre>

'''this.slideTemporaryObject(mobile_obj_html: string, parent: ElementOrId, from: ElementOrId, to: ElementOrId, duration?: number, delay?: number): Animation'''

This method is useful when you want to slide a temporary HTML object from one place to another. As this object does not exists before the animation and won't remain after, it could be complex to create this object (with dojo.place), to place it at its origin (with placeOnObject) to slide it (with slideToObject) and to make it disappear at the end.

slideTemporaryObject does all of this for you:
* mobile_obj_html is a piece of HTML code that represent the object to slide.
* parent is the ID of an HTML element of your interface that will be the parent of this temporary HTML object.
* from is the ID of the origin of the slide.
* to is the ID of the target of the slide.
* duration/delay works exactly like in "slideToObject"

Example:
<pre>
this.slideTemporaryObject( '<div class="token_icon"></div>', 'tokens', 'my_origin_div', 'my_target_div' ).play();
</pre>

===Destroy===
'''this.slideToObjectAndDestroy(mobile_obj: ElementOrId, target_obj: ElementOrId, duration?: number, delay?: number): void'''

This method is a handy shortcut to slide an existing HTML object to some place then destroy it upon arrival. It can be used for example to move a victory token or a card from the board to the player panel to show that the player earns it, then destroy it when we don't need to keep it visible on the player panel.

It works the same as this.slideToObject and takes the same arguments, but it starts the animation.

CAREFUL: Make sure nothing is creating the same object at the same time the animation is running, because this will cause some random disappearing effects

Example:
<pre>
this.slideToObjectAndDestroy( "some_token", "some_place_on_board", 1000, 0 );
</pre>

'''this.fadeOutAndDestroy( node: string | Element, duration?: number, delay?: number):''' '''void'''

This function fade out the target node, then destroy it. Its starts the animation.
* duration/delay works exactly like in "slideToObject"

Example:
<pre>
this.fadeOutAndDestroy( "a_card_that_must_disappear" );
</pre>

CAREFUL: the HTML node still exists until during few milliseconds, until the fadeOut has been completed.
Make sure nothing is creating same object at the same time as animation is running, because you will be some random dissapearing effects

===Rotating elements===

This example combines "Dojo.Animation" method and a CSS property transform that allow you to rotate the element.
<pre>
// node is Element we rotating
var animation = new dojo.Animation({
curve: [fromDegree, toDegree],
onAnimate: (v) => {
node.style.transform = 'rotate(' + v + 'deg)';
}
});

animation.play();
</pre>

BGA has its own interface to rotate

'''this.rotateTo(node: string | Element, degree: number): void'''

It starts the animation, and stored the rotation degree in the class, so next time you rotate object - it is additive.
There is no animation hooks in this one, if you need to change any parameters use dojo animation above.

There is also '''rotateInstantTo''' with same signature which does not animate

===Animation Callbacks===

If you wish to run some code only after an animation has completed you can do this by linking a callback method to 'onEnd'.

<pre>
var animation_id = this.slideToObject( mobile_obj, target_obj, 500 );
dojo.connect(animation_id, 'onEnd', () => {
// do something here
});
animation_id.play();
</pre>

If you wish to call a second animation after the first (rather than general code) then you can use a dojo animation chain (see tutorial referenced above).

== Players input ==

=== Connecting ===
'''dojo.connect(element: Element, event: string, context: object, method: eventHandler): any'''

'''dojo.connect(element: Element, event: string, handler: eventHandler): any'''

Used to associate a player event with one of your notification methods.

Example: associate a click on an element ("my_element") with one of our methods ("onClickOnMyElement"):
<pre>
dojo.connect( $('my_element'), 'onclick', this, 'onClickOnMyElement' );
</pre>

Same idea but based on query (i.e. all element of 'pet' class)
dojo.query(".pet").connect('onclick', this, 'onPet');

Note: if you need to disconnect the handler you have to store handler returned from this method, i.e.

<pre>
var handler = dojo.connect(...);
...
dojo.disconnect(handler);
</pre>

If you don't store the handler - you have to destroy the object to disconnect it

Typical function that implements the input handler will look like this

<pre>
onPet: function(event) {
var id = event.currentTarget.id;
console.log('onPet ' + id);
dojo.stopEvent(event);
if (this.gamedatas.gamestate.name == 'playerTurnPet') {
this.bgaPerformAction('actPlayPet', {card: id});
} else {
this.showMoveUnauthorized();
}
}
</pre>

'''this.connect(element: ElementOrId, event: string, method: eventHandler): void'''

Used to associate a player event with one of your notification methods.

this.connect( $('my_element'), 'onclick', 'onClickOnMyElement' );

Or you can use an in-place handler

this.connect( $('my_element'), 'onclick', (e) => { console.log('boo'); } );

Note that this function stores the connection handler. That is the only real difference between '''this.connect''' and '''dojo.connect'''. If you plan to destroy the element you connected, you '''must''' call this.disconnect() to prevent memory leaks.
This function is mainly for permanent objects - if you just want to connect the temp object you should probably not use this method but use dojo.connect which won't require any clean-up.

'''this.connectClass(cssClassName: string, event: string, method: eventHandler): void'''

Same as connect(), but for all the nodes set with the specified cssClassName.

this.connectClass('pet', 'onclick', 'onPet');

'''this.disconnect(element: ElementOrId, event: string): void'''

Disconnect event handler (previously registered with this.connect or this.connectClass).

this.disconnect( $('my_element'), 'onclick');

Note: dynamic connect/disconnect is for advanced cases ONLY, you should always connect elements statically if possible, i.e. in setup() method.

'''this.disconnectAll(): void'''

Disconnect all previously registed event handlers (registered via this.connect or this.connectClass)

this.disconnectAll();

=== Actions ===

'''this.bgaPerformAction(action: string, args?: object, options: object = { lock: true, checkAction: true }): Promise<void>'''

Triggers an action on the backend. This is a combination of checkAction and ajaxcall, returning a Promise which resoves when ajaxcall ends.

This method must be used to send a player input to the game server. '''It should not be triggered programmatically''', especially not in loops, in callbacks, in notifications, or in onEnteringState/onUpdateActionButtons/onLeavingState, in order not to create race conditions or break replay game and tutorial features. It should be used only in reaction to a user action in the interface.

* action: name of the action, as it is written in "possibleactions" of the current state.
* args: an object containing the call parameters to send to the action
* options: options to tweak the call with some defaults. Default is <code>{ lock: true, checkAction: true }</code>.

Example of a standard call without args:
this.bgaPerformAction('pass');

Example of a standard call with action args:
this.bgaPerformAction('actPlayCard', { id: this.selectedCardId });

Example of a call without checking action (because player is inactive in a multiactive state):

this.bgaPerformAction('actChangeMind', {}, { checkAction: false });

Example of a call without lock (because of a special action not directly related to the game flow):

this.bgaPerformAction('actSetAutoBid', { alwaysBidUntil: 500 }, { lock: false, checkAction: false });

Example of call with reaction to exception:
this.bgaPerformAction('actPlayCard', { id: this.selectedCardId }).catch(()=>{ this.selectedCardId = undefined; });

Example of call with reaction to success:
this.bgaPerformAction('actPlayCard', { id: this.selectedCardId }).then(()=>{ this.unselectAll(); });

'''this.ajaxcall(url, parameters, obj_callback, callback, callback_anycase?, ajax_method?: string)'''

''Note: bgaPerformAction is a simpler way to use ajax calls, ajaxcall stays in the doc for legacy reasons only and should not be used in new projects.''

Same warning as '''this.bgaPerformAction''' about using on user action only.

* url: the url of the action to perform. For a game, it must be: "/<mygame>/<mygame>/myAction.html"
* parameters: an array of parameter to send to the game server.
** Note that "lock: true" must always be specified in this list of parameters in order the interface can be locked during the server call. Cannot use lock: false - to not lock it has to be undefined.
** Note: Restricted parameter names (please don't use them):
*** "action"
*** "module"
*** "class"
* obj_callback: must be set to "this".
* callback (non-optional but rarely used): a function to trigger when the server returns result and everything went fine (not used, as all data handling is done via notifications).
* callback_anycase: (optional) a function to trigger when the server returns ok OR error. If no error this function is called with parameter value false. If an error occurred, the first parameter will be set to true, the second will contain the error message sent by the PHP back-end, and the third will contain an error code.
* ajax_method: (optional and rarely used) if you need to send large amounts of data (over 2048 bytes), you can set this parameter to 'post' (all lower-case) to send a POST request as opposed to the default GET. This works, but was not officially documented, so only use if you really need to.

Usage:
<pre>
this.ajaxcall( '/mygame/mygame/actMyAction.html', { lock: true,
arg1: myarg1,
arg2: myarg2
}, this, (result)=>{} );
</pre>

'''this.checkAction(action: string, nomessage?: boolean): boolean '''

Check if player can do the specified action by taking into account:
* if interface is locked it will return false and show message "An action is already in progress", unless nomessage set to true
* if player is not active it will return false and show message "This is not your turn", unless nomessage set to true
* if action is not in list in possible actions (defined by "possibleaction" in current game state) it will return false and show "This move is not authorized now" error (unconditionally).
* otherwise returns true
Example:
<pre>
function onClickOnGameElement( evt ) {
if( this.checkAction( "actMyAction" ) ) {
// Do the action
}
}
</pre>

'''this.checkPossibleActions(action: string): boolean'''

* this is independent of the player being active, so can be used instead of this.checkAction(). This is particularly useful for multiplayer states when the player is not active in a 'player may like to change their mind' scenario. Unlike this.checkAction, this function does NOT take interface locking into account

* if action is not in list in possible actions (defined by "possibleaction" in current game state) it will return false and show "This move is not authorized now" error (unconditionally).
* otherwise returns true

function onChangeMyMind( evt ) {
if( this.checkPossibleActions( "actMyAction" ) ) {
// Do the action
}
}

'''this.checkLock(nomessage?: boolean): boolean'''

When using "lock: true" in ajax call you can use this function to check if interface is in lock state (it will be locked during server call and notification processing).
This check can be used to block some other interactions which do not result in ajaxcall or if you want to suppress errors. Note: normally you only need to use this.checkAction(...), this is for advanced cases.

It will also show error unless nomessage is set to true

function onChangeMyMind( evt ) {
if( this.checkLock() ) {
// Do the action
}
}

== Notifications ==

When something happens on the server side, your game interface Javascript logic received a notification.
If you have not done so yet check what notification are in [[Main_game_logic:_yourgamename.game.php#Notifications]]

Here's how you can handle these notifications on the client side.

=== Subscribe to notifications ===

'''dojo.subscribe(notif_type: string, callback_obj: Object, handler: string|handler)'''
* notif_type - notification type/name send by php server
* callback_obj - usually this
* handler - if string method of callback_obj with name name is called, when notification is called, with notification object as parameter (see below)

Your Javascript "setupNotifications" method is the place where you can subscribe to notifications from your PHP code.

Here's how you associate one of your Javascript method to a notification "playDisc" (from Reversi example):

<pre>
setupNotifications: function() {
...
dojo.subscribe('playDisc', this, "notif_playDisc");
},
</pre>

Note: the "playDisc" corresponds to the name of the notification you define it in your PHP code, in your "notifyAllPlayers" or "notifyPlayer" method.

Then, you have to define your "notif_playDisc" method:

<pre>
notif_playDisc: function(notif) {
// Remove current possible moves (makes the board more clear)
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );
this.addDiscOnBoard( notif.args.x, notif.args.y, notif.args.player_id );
},
</pre>

In a notification handler like our "notif_playDisc" method, you can access all notifications arguments with "notif.args".

Example:

PHP

<pre>
$this->notifyAllPlayers( "apples", clienttranslate('player takes ${count} apples'), [ "count" => 3 ] );
</pre>

JavaScript

<pre>
setupNotifications: function() {
dojo.subscribe( 'apples', this, 'notif_apples' );
},

notif_apples: function(notif) {
//You can access the "count" like this:
alert("count = " + notif.args.count);
}
</pre>

=== The notification Object received by client ===

When sending a notification on your PHP, the client side will receive an Object with the following attributes:

* type - type of the notification (as passed by php function)
* log - the log string passed from php notification
* args - This is the arguments that you passed on your notification method on php
* bIsTableMsg - is true when you use [[Main_game_logic:_yourgamename.game.php#NotifyAllPlayers|NotifyAllPlayers]] method (false otherwise)
* channelorig - information about table ID (formatted as : "/table/t[TABLE_NUMBER]")
* gamenameorig - name of the game
* move_id - ID of the move associated with the notification
* table_id - ID of the table (comes as string)
* time - UNIX GMT timestamp
* uid - unique identifier of the notification
* h - unknown

'' Note that those information were inferred from observation on console log. If an Admin can confirm/correct (and remove this line), you're welcome :)''

=== Ignoring notifications ===

Sometimes you need to ignore some notification on client side. You don't want them to be shown in game log and you don't want them to be handled.

The most common use case is when a player gets private information. They will receive a specific notification (such as "You received Ace of Heart"), while other players would receive more generic notification ("Player received a card").

In X.game.php
<pre>
$this->notifyAllPlayers("dealCard", clienttranslate('${player_name} received a card'), [
'player_id' => $playerId,
'player_name' => $this->getActivePlayerName()
]);

$this->notifyPlayer($playerId, "dealCardPrivate", clienttranslate('You received ${cardName}'), [
"type" => $card["type"],
"cardName" => $this->getCardName($card["type"])
]);
</pre>

The problem with this approach is that the active player will receive two notifications:
* Player1 received a card
* You received Ace of Hearts

Hence, notification ignoring.

NOTE: You can think that it would be possible to send such notification to all players except active just by using notifyPlayer and it seems to work. The problem however is that table spectators would miss such notification and their user interface (and game log) wouldn't be updated. Since there is no way to send notification just to spectators, ignoring the notification (or "filtering") is the only reasonable solution.

'''setIgnoreNotificationCheck(notif_type: string, predicate: ((notif: Notif)=>boolean))'''
This method will set a check whether any of notifications of specific type should be ignored.

The parameters are:
* notif_type: type of the notification
* predicate (notif => boolean): a function that will receive notif object and will return true if this specific notification should be ignored

Before dispatching any notification of this type, the framework will call predicate to check whether notification should be ignored, if it return true - the notification will be dispatched, i.e. logged or handled.

<pre>
this.notifqueue.setIgnoreNotificationCheck( 'dealCard', (notif) => (notif.args.player_id == this.player_id) );
</pre>

IMPORTANT: Remember that this notification is ignored on the client side, but was still received by the client. Therefore it shouldn't contain any private information as cheaters can get it. In other words this is not a way to hide information.

IMPORTANT: When a game is reloaded with F5 or when opening a turn based game, old notifications are replayed as history notification. They are used just to update the game log and are stripped of all arguments except player_id, i18n and any argument present in message. If you use and other argument in your predicate you should '''preserve''' it as explained [[Main_game_logic:_yourgamename.game.php#Notify_players|here]].

=== Synchronous notifications ===

When several notifications are received by your game interface, these notifications are processed immediately, one after the other, in the same exact order they have been generated in your PHP game logic.

However, sometimes, you need to give some time to the players to figure out what happened on the game before jumping to the next notification. Indeed, in many games, there are a lot of automatic actions, and the computer is going to resolve all these actions very fast if you don't tell it not to do so.

As an example, for Reversi, when someone is playing a disc, we want to wait 500 milliseconds before doing anything else in order the opponent player can figure out what move has been played.

Here's how we do this, right after our subscription:
<pre>
dojo.subscribe( 'playDisc', this, "notif_playDisc" );
this.notifqueue.setSynchronous( 'playDisc', 500 ); // Wait 500 milliseconds after executing the playDisc handler
</pre>

-----

It is also possible to control the delay timing dynamically (e.g., using notification args). As an example, maybe your notification 'cardPlayed' should pause for a different amount of time depending on the number or type of cards played.

For this case, use '''setSynchronous''' without specifying the duration and use '''setSynchronousDuration''' within the notification callback.

* NOTE: If you forget to invoke '''setSynchronousDuration''', the game will remain paused forever!

<pre>
setupNotifications: function () {
dojo.subscribe( 'cardPlayed', this, 'notif_cardPlayed' );
this.notifqueue.setSynchronous( 'cardPlayed' ); // wait time is dynamic
...
},

notif_cardPlayed: function (notif) {
// MUST call setSynchronousDuration

// Example 1: From notification args (PHP)
this.notifqueue.setSynchronousDuration(notif.args.duration);
...

// Or, example 2: Match the duration to a Dojo animation
var anim = dojo.fx.combine([
...
]);
anim.play();
this.notifqueue.setSynchronousDuration(anim.duration);
},
</pre>

You can also manually call this.notifqueue.setSynchronousDuration(0) once client operations are finished, but be careful that even fast replay still has a path to call it.

'''WARNING: combining synchronous and ignored notifications'''
You must be careful when combining dynamic synchronous durations (as described above) with ignored notifications. If you have a conditionally ignored notification like this (see below section):

<pre>this.notifqueue.setIgnoreNotificationCheck( 'myNotif', (notif) => (notif.args.player_id == this.player_id) /* or any other condition */ )</pre>

then you CANNOT do

<pre>this.notifqueue.setSynchronous('myNotif');</pre>

as, when the ignored check passes, the notification handler, in which `this.notifqueue.setSychronousDuration` is called, is never called and so the duration is never set and interface locking results.

The workaround is to set a "dummy" time:

<pre>this.notifqueue.setSynchronous('myNotif', 5000);</pre>

whose value is irrelevant but must be large enough to cover the time before the notification handler is called. The large value never actually comes into play because the notification is either ignored, or the synchronous duration is reset to a sensible value inside the handler.

=== Pre-defined notification types ===

'''tableWindow''' - This defines notification to display [[Game_interface_logic:_yourgamename.js#Scoring_dialogs|Scoring Dialogs]], see below.

'''message''' - This defines notification that shows on players log and have no other effect (technically any unhandled notification will do the same but its recommended to use this keyword for consistency)

// You can call this on php side without doing anything on client side
self::notifyAllPlayers( 'message', clienttranslate('hello'), [] );

'''simplePause''' - This notification will just delay other notifications, maybe useful if you know you need some extra time for animation or something. Requires a time parameter.

<pre>
self::notifyAllPlayers( 'simplePause', '', [ 'time' => 500] ); // time is in milliseconds
</pre>

Note: the following types are RESERVED by framework, do not use:

gameStateChange gameStateChangePrivateArg gameStateMultipleActiveUpdate newActivePlayer playerstatus yourturnack clockalert tableInfosChanged playerEliminated tableDecision archivewaitingdelay end_archivewaitingdelay replaywaitingdelay end_replaywaitingdelay replayinitialwaitingdelay end_replayinitialwaitingdelay aiPlayerWaitingDelay replay_has_ended updateSpectatorList wouldlikethink updateReflexionTime undoRestorePoint resetInterfaceWithAllDatas zombieModeFail zombieModeFailWarning aiError skipTurnOfPlayer zombieBack allPlayersAreZombie gameResultNeutralized playerConcedeGame showTutorial showCursor showCursorClick skipTurnOfPlayerWarning banFromTable resultsAvailable switchToTurnbased newPrivateState infomsg

== Tooltips ==

=== Adding static tooltips ===

'''this.addTooltip(nodeId: string, helpStringTranslated: string, actionStringTranslated: string, delay?: number): void'''

Add a simple text tooltip to the DOM node.

Specify 'helpStringTranslated' to display some information about "what is this game element?".
Specify 'actionStringTranslated' to display some information about "what happens when I click on this element?".

You must specify both of the strings. You can only use one and specify an empty string ('') for the other one.

When you pass text directly function _() must be used for the text to be marked for translation! Except for empty string.

Parameter "delay" is optional. It is primarily used to specify a zero delay for some game element when the tooltip gives really important information for the game - but remember: no essential information must be placed in tooltips as they won't be displayed in some browsers (see [[BGA_Studio_Guidelines|Guidelines]]).

Example:
<pre>
this.addTooltip( 'cardcount', _('Number of cards in hand'), '' );
</pre>

Note: this generates static tooltip and attaches to existing dom element, if you need to generate tooltip more dynamically you have to call that method every time information about object is updated or use completely different tehnique, see dynamic tooltips below.

'''this.addTooltipHtml(nodeId: string, html: string, delay?: number): void'''

Add an HTML tooltip to the DOM node (for more elaborate content such as presenting a bigger version of a card).

'''this.addTooltipToClass(cssClass: string, helpStringTranslated: string, actionStringTranslated: string, delay?: number ): void'''

Add a simple text tooltip to all the DOM nodes set with this cssClass. See more details above for this.addTooltip.
this.addTooltipToClass( 'meeple', _('This is A Meeple'), _('Click to tickle') );

IMPORTANT: all concerned nodes must exist and have IDs to get tooltips.

'''this.addTooltipHtmlToClass(cssClass: string, html: string, delay?: number): void'''

Add an HTML tooltip to to all the DOM nodes set with this cssClass (for more elaborate content such as presenting a bigger version of a card).

IMPORTANT: all concerned nodes must exist and have IDs to get tooltips.

=== Removing static tooltips ===

'''this.removeTooltip(nodeId: string): void'''

Remove a tooltip from the DOM node with given id.

=== Advanced tooltips ===

'''force tooltip to open'''

If you want to force tooltip to open in reaction to some other action, i.e. click you can do this

this.tooltips[id].open(id)

where id is the id of the tooltip node where tooltip was installed.

'''dynamic tooltips'''

See [[BGA_Studio_Cookbook#Dynamic_tooltips]]

'''tooltips on mobile'''

Tooltips is very unreliable on mobile, it is recommended to implement some other method to obtaining same information,
such as simple click handler in dedicated "Help" mode or provide dedicated clickable areas such as corner of card.

== Warning messages ==

Sometimes, there is something important that is happening in the game and you have to make sure all players get the message. Most of the time, the evolution of the game situation or the game log is enough, but sometimes you need something more visible.

Ex: someone fulfills one of the end of the game conditions, so this is the last turn.

'''this.showMessage(msg: string, type: string): void'''

showMessage shows a message in a big rectangular area on the top of the screen of the current player, and it dissapears after few seconds (also it will be in the log in some cases).

* "msg" is the string to display. It should be translated.
* "type" can be set to "info", "error", "only_to_log" or custom string. If set to "info", the message will be an informative message on a white background. If set to "error", the message will be an error message on a red background and it will be added to log. If set to "only_to_log", the message will be added to the game log but will not popup at the top of the screen.
If set to custom string, it will be transparent, to use custom type define "head_xxx" in css, where xxx is the type. For example if you want yellow warning, use "warning" as type and add this to css:
.head_warning {
background-color: #e6c66e;
}

Important: the normal way to inform players about the progression of the game is the game log. The "showMessage" is intrusive and should not be used often.

<pre>
notif_messageinfo: function(notif) {
if (!g_archive_mode) {
var message = this.format_string_recursive(notif.log, notif.args);
this.showMessage(_('Announcement:') + " " + message, 'info');
}
},
</pre>

Show message could be used on the client side to prevent user wrong moves before it is send to server.
Example from 'battleship':
<pre>
onGrid: function(event) {
if (checkIfPlayerTriesToFireOnThemselves(event)) {
this.showMessage(_('This is your own board silly!'), 'error');
return;
}
...
},
</pre>

'''this.showMoveUnauthorized(): void'''

Shows predefined user error that move is unauthorized now

<pre>
onPet: function(event) {
if (checkPet(event)==false) {
this.showMoveUnauthorized();
return;
}
...
},
</pre>

== Dialogs ==

=== Confirmation dialog ===

When an important action with a lot of consequences is triggered by the player, you may want to propose a confirmation dialog.

CAREFUL: the general guideline of BGA is to AVOID the use of confirmation dialogs. Confirmation dialogs slow down the game and bother players. The players know that they have to pay attention to each move when they are playing online.

The situations where you should use a confirmation dialog are the following:
* It must not happen very often during a game.
* It must be linked to an action that can really "kill a game" if the player does not pay attention.
* It must be something that can be done by mistake (ex: a link on the action status bar).

'''this.confirmationDialog(message: string, yesHandler: (param: any) => void, noHandler?: (param: any) => void, param?: any): void'''

* message - message will be shown to user, use _() to translate
* yesHandler - non-optional handler to be called on yes
* noHandler - optional handler to called on no
* param - if specified, it will be passed to both handlers
NOTE: this is async function, it does not return anything and you should not do anything after, you must do everything in handlers

How to display a confirmation dialog:
<pre>
this.confirmationDialog(_("Are you sure you want to bake a pie?"), () => {
this.bakeThePie();
});
return; // nothing should be called or done after calling this, all action must be done in the handler
</pre>
With param and both handlers
<pre>
this.confirmationDialog(_("Are you sure you want to bake a pie?"),
(ingredient) => this.bakeThePie(ingredient),
(ingredient) => console.log(`cancelled baking of ${ingredient}`),
'apple');
</pre>

=== Multiple choice dialog ===

You can use this dialog to give user a choice with small amount of options

'''this.multipleChoiceDialog(message: string, choices: string[], callback: (choice: number) => void): void'''
* message - message will be shown to user, use _() to translate
* choices - array of choices
* callback - non-optional handler to be called on choice made, the choice parameter is the INDEX of the choice from the array of choices

NOTE: this is async function, it does not return anything and you should not do anything after, you must do everything in handlers
NOTE: there is no cancel handler, so make sure you gave user a choice to get out of it

Example:
<pre>
const keys = ["0", "1", "5", "10"];
this.multipleChoiceDialog(_("How many bugs to fix?"), keys, (choice) => {
if (choice==0) return; // cancel operation, do not call server action
var bugchoice = keys[choice]; // choice will be 0,1,2,3 here
this.bgaPerformAction("fixBugs", { number: bugchoice });
});
return; // must return here
</pre>

=== Generic Dialogs ===

As a general rule, you shouldn't use dialogs windows.

BGA guidelines specify that all game elements should be displayed on the main screen. Players can eventually scroll down to see game elements they don't need to see anytime, and you may eventually create anchors to move between game area section. Of course dialogs windows are very practical, but the thing is: all players know how to scroll down, and not all players know how to show up your dialog window. In addition, when the dialog shows up, players can't access the other game components.

Sometimes although, you need to display a dialog window. Here is how you do this:

// Create the new dialog over the play zone. You should store the handler in a member variable to access it later
this.myDlg = new ebg.popindialog();
this.myDlg.create( 'myDialogUniqueId' );
this.myDlg.setTitle( _("my dialog title to translate") );
this.myDlg.setMaxWidth( 500 ); // Optional

// Create the HTML of my dialog.
// The best practice here is to use [[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl#Javascript_templates|Javascript templates]]
var html = this.format_block( 'jstpl_myDialogTemplate', {
arg1: myArg1,
arg2: myArg2,
...
} );

// Show the dialog
this.myDlg.setContent( html ); // Must be set before calling show() so that the size of the content is defined before positioning the dialog
this.myDlg.show();

// Now that the dialog has been displayed, you can connect your method to some dialog elements
// Example, if you have an "OK" button in the HTML of your dialog:
dojo.connect($('my_ok_button'), 'onclick', this, (event) => {
event.preventDefault();
this.myDlg.destroy();
});

If necessary, you can remove the default top right corner 'close' icon, or replace the function called when it is clicked:
// Removes the default close icon
this.myDlg.hideCloseIcon();

// Replace the function call when it's clicked
this.myDlg.replaceCloseCallback((event) => { ... });

=== Scoring dialogs ===

Sometimes at the end of a round you want to display a big table that details the points wins in each section of the game.

Example: in Hearts game, we display at the end of each round the number of "heart" cards collected by each player, the player who collected the Queen of Spades, and the total number of points loose by each player.

Scoring dialogs are managed entirely on '''PHP side''', but they are described here as their effects are visible only on client side.

Displaying a scoring dialog is quite simple and is using a special notification type: "tableWindow":
<pre>
// on PHP side:
$this->notifyAllPlayers( "tableWindow", '', array(
"id" => 'finalScoring',
"title" => clienttranslate("Title of the scoring dialog"),
"table" => $table
));
</pre>

The "table" argument is a 2 dimensional PHP array that describes the table you want to display, line by line and column by column.

Example: display an 3x3 array of strings
<pre>
$table = [
[ "one", "two", "three" ], // This is my first line
[ "four", "five", "six" ], // This is my second line
[ "seven", "height", "nine" ] // This is my third line
];
</pre>

As you can see above, in each "cell" of your array you can display a simple string value. But you can also display a complex value with a template and associated arguments like this:
<pre>
$table = [
[ "one", "two", [ "str" => clienttranslate("a string with an ${argument}"), "args" => [ 'argument' => 'argument_value' ] ] ],
[ "four", "five", "six" ],
[ "seven", "height", "nine" ]
];
</pre>

This is especially useful when you want to display player names with colors. Example from "Hearts":
<pre>
$firstRow = [ '' ];
foreach( $players as $player_id => $player ) {
$cell = [ 'str' => '${player_name}',
'args' => [ 'player_name' => $player['player_name'] ],
'type' => 'header'
];
$firstRow[] = $cell;
}
$table[] = $firstRow;
...
</pre>

You can also use three extra attributes in the parameter array for the notification:
* '''header''': the content for this parameter displays before the table (also, the html will be parsed and player names will be colored according to the current game colors).
* '''footer''': the content for this parameter displays after the table (no parsing for coloring the player names)
* '''closing''': if this parameter is used, a button will be displayed with this label at the bottom of the popup and will allow players to close it (more easily than by clicking the top right 'cross' icon).

<pre>
$this->notifyAllPlayers( "tableWindow", '', [
"id" => 'finalScoring',
"title" => clienttranslate("Title of the scoring dialog"),
"table" => $table,
"header" => ['str' => clienttranslate('Table header with parameter ${number}'),
'args' => [ 'number' => 3 ],
],
"footer" => '<div class="myfoot"></div>',
"closing" => clienttranslate( "Closing button label" )
] );
</pre>

Note: currently id is not used - so you cannot access resulting div by id on js side
Note: any traslatable stirng have to be wrapped by clienttranslate() on top level OR it has to be recursive template.

DO NOT DO THIS:
<pre>
"footer" => '<div>'.clienttranslate( "The end" ).'</div>', // this will not work for translations!!!
</pre>

=== Scoring animated display ===

Sometimes, you may want to display a score value over an element to make the scoring easier to follow for the players (Terra Mystica final scoring for example).
You can do it with:

'''this.displayScoring(anchor_id: string, color: string, score: number | string, duration?: number, offset_x?: number, offset_y?: number): void'''

'''anchor_id''': ID of the html element to place the animated score onto (without the '#')

'''color''': hexadecimal RGB representation of the color (should be the color of the scoring player), but without a leading '#'. For instance, 'ff0000' for red.

'''score''': numeric score to display, prefixed by a '+' or '-'

'''duration''': animation duration in milliseconds (optional, default is 1000)

'''offset_x''' and '''offset_y''': if both offset_x and offset_y are defined and not null, apply the following offset (in pixels) to the scoring animation.
Note that the score is centered in the anchor, so the offsets might have to be negative if you calculate the position.

Note: if you want to display successively each score, you can use ''this.notifqueue.setSynchronous()'' function.
<pre>
setupNotifications: function() {
dojo.subscribe( 'displayScoring', this, "notif_displayScoring" );
...
}
...

notif_displayScoring: function(notif) {
const duration = notif.args.duration?notif.args.duration:1000;
this.notifqueue.setSynchronous('displayScoring', duration );
this.displayScoring( notif.args.target, notif.args.color, notif.args.score, duration);
},
</pre>

=== Speech bubble ===

For better interactivity in some games (Love Letter for example), you may use comic book style speech bubbles to express the players voices.
This is done with showBubble:

'''this.showBubble(anchor_id: string, text: string, delay?: number, duration?: number, custom_class?: string): void'''

* anchor_id - where to attach the bubble
* text - what to put in bubble, can be html
* delay - delay in milliseconds (optional, default 0)
* duration - duration of animation in milliseconds (optional, default 3000)
* custom_class - extra class to add to bubble (optional), if you need to override the default bubble style

<pre>
this.showBubble('meeple_2', _('Hello'), 0, 1000, 'pink_bubble');
</pre>

<pre>
notif_speechBubble(notif) {
var html = this.format_string_recursive(notif.args.text, notif.args.args);
this.showBubble(notif.args.target, html, notif.args.delay ?? 0, notif.args.duration ?? 1000);
},
</pre>

'''Warning''': if your bubble could overlap other active elements of the interface (buttons in particular), as it stays in place even after disappearing, you should use a custom class to give it the style "pointer-events: none;" in order to intercept click events.

Note: If you want this visually, but want to take complete control over this bubble and its animation (for example to make it permanent) you can just use div with 'discussion_bubble' class on it, and content of div is what will be shown.

== Translations ==

See [[Translations]]

== Players panels ==

=== Update players score ===

The column player_score from the player table is automatically loaded into this.scoreCtrl and therefore into the stars location on the player board. This occurs sometime after the game setup() function. However this score must be updated as the game progresses using notifications.

Note: this.scoreCtrl[player_id] is object of class [[Counter]], you can use other counter API.

Increase a player score (with a positive or negative number):

<pre>
this.scoreCtrl[ player_id ].incValue( score_delta );
</pre>

Set a player score to a specific value:

<pre>
this.scoreCtrl[ player_id ].setValue( new_score );
</pre>

Set a player score to a specific value with animation:

<pre>
this.scoreCtrl[ player_id ].toValue( new_score );
</pre>

Typical usage would be (that will process 'score' notification):
<pre>
setupNotifications : function() {
...
dojo.subscribe('score', this, "notif_score");
},
notif_score: function(notif) {
this.scoreCtrl[notif.args.player_id].setValue(notif.args.player_score);
},
</pre>

=== Adding stuff to player's panel ===

At first, create a new "JS template" string in your template (tpl) file:

(from Gomoku example)
<pre>
var jstpl_player_board = '\<div class="cp_board">\
<div id="stoneicon_p${id}" class="gmk_stoneicon gmk_stoneicon_${color}"></div><span id="stonecount_p${id}">0</span>\
</div>';
</pre>

Then, you add this piece of code in your JS file to add this template to each player panel:

<pre>
// Setting up player boards
for( var player_id in gamedatas.players )
{
var player = gamedatas.players[player_id];

// Setting up players boards if needed
var player_board_div = $('player_board_'+player_id);
dojo.place( this.format_block('jstpl_player_board', player ), player_board_div );
}
</pre>

(Note: the code above is of course from your "setup" function in your Javascript).

Very often, you have to distinguish current player and others players. In this case, you just have to create another JS template (ex: jstpl_otherplayer_board) and use it when "player_id" is different than "this.player_id".

=== Fixing Player Panel heights ===

You may find that the player panels don't automatically resize when adding something to (or removing something from) a player panel while the display is in portrait mode (i.e. the player summary panels are at the top of the screen rather than down the right side).

When this happens, call <pre>this.adaptPlayersPanels();</pre> This recalculates the layout and also adjusts the position of the actionbar for you.

=== Player's panel disabling/enabling ===

'''this.disablePlayerPanel(player_id: number): void'''

Disable given player panel (the panel background become gray).

Usually, this is used to signal that this played passes, or will be inactive during a while.

Note that the only effect of this is visual. There are no consequences on the behaviour of the panel itself.

'''this.enablePlayerPanel(player_id:number): void'''

Enable a player panel that has been disabled before.

'''this.enableAllPlayerPanels(): void'''

Enable all player panels that has been disabled before.

=== Player order ===

'''this.updatePlayerOrdering(): void'''

This function makes sure that player order in player's panel matches this.gamedatas.playerorder and its normally called by framework.
You can call it yoursel if you change this.gamedatas.playerorder from notification.
Also you can override this function to change defaults OR insert a non-player panel [[BGA_Studio_Cookbook#Inserting_non-player_panel]].

=== Counters ===
Note: there is bga component called "ebg/counter" this API is not using it, these methods
below declared right in core game. If you need animation for counters use ebg/counter

To use this API just create a counter dom element like this (class does not really matter)
<pre>
<div class="counter" id="bread"></div>
<div class="counter" id="coin"></div>
</pre>
The "bread" will the counter name.

The php code should send all "counters" data from getAllDatas() method like this

game.php
<pre>
protected function getAllDatas() {
// (the key must match counter_name)
$result['counters']=[
'bread' => [
'counter_name' => 'bread',
'counter_value' => 3
],
'coin' => [
'counter_name' => 'coin',
'counter_value' => 5
]
];
return $result;
}
</pre>

'''setCounter(counter_name: stirng, new_value: string | number): void'''

updates the global this.gamedatas.counters and value of node $(counter_name)
<pre>
notif_counter: function(notif) {
this.setCounter(notif.args.counter_name, notif.args.counter_value);
},
</pre>

'''incCounter(counter_name: string, delta: number): void'''
<pre>
notif_counter : function(notif) {
this.incCounter(notif.args.counter_name, notif.args.inc);
},
</pre>

'''updateCounters(counters: object): void'''

Useful for updating game counters in the player panel (such as resources).
'counters' arg is map of counters (the key must match counter_name)
{
'bread': {
'counter_name' : 'bread',
'counter_value' => 3
},
'coin': {
'counter_name' : 'coin',
'counter_value' => 5
}
}
All counters MUST be referenced in this.gamedatas.counters (means they should be send from php) and will be updated.
DOM objects referenced by 'counter_name' will have their innerHTML updated with 'counter_value'.

Usually you call this from notification

<pre>
notif_counter : function(notif) {
this.updateCounters(notif.args.counters);
},
</pre>

== BGA GUI components ==

BGA framework provides some useful ready-to-use components for the game interface:

[[Studio#BGA_Studio_game_components_reference]]

Note that each time you are using an additional component, you must declare it at the top of your Javascript file in the list of modules used.

Example if you are using "ebg.stock":
<pre>
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/stock" /// <=== we are using ebg.stock module
],
</pre>

== BGA Buttons ==

=== Basic Button ===

'''this.addActionButton(id: string, label: string, method: string | eventhandler, destination?: string, blinking?: boolean, color?: string): void'''

You can use this method to add an action button in the main action status bar (or other places).

Arguments:
* id: an element ID that should be unique in your HTML DOM document.
* label: the text of the button. Should be translatable (use _() function). Note: this can also be any html, such as "<div class='brick'></div>", see example below on how to make image action buttons.
* method: the name of your method that must be triggered when the player clicks on this button (can be name of the method on game class or handler).
* destination (optional): id of parent on where to add button, ONLY use in rare cases if location is not action bar. Use '''null''' as value if you need to specify other arguments.
* blinking (optional): if set to '''true''', the button is going blink to catch player's attention. Please DO NOT abuse blinking button. If you need button to blink after some time passed add class 'blinking' to the button later.
* color: could be '''blue''' (default), '''red''','''gray''' or '''none'''.

You should only use this method in your "onUpdateActionButtons" method. Usually, you use it like this:

<pre>
onUpdateActionButtons: function( stateName, args ) {
if (this.isCurrentPlayerActive()) {
switch( stateName ) {
case 'giveCards':
this.addActionButton( 'giveCards_button', _('Give selected cards'), 'onGiveCards' );
this.addActionButton( 'pass_button', _('Pass'), () => this.bgaPerformAction('actPass') );
break;
}
}
},
</pre>

In the example above, we are adding a "Give selected cards" button in the case we are on game state "giveCards". When player clicks on this button, it triggers our "onGiveCards" method.

Example using blinking red button:
<pre>
this.addActionButton( 'button_confirm', _('Confirm?'), 'onConfirm', null, true, 'red');
</pre>

If you want to call the handler with arguments, you can use arrow functions, like this:
<pre>
this.addActionButton( 'commit_button', _('Confirm'), () => this.onConfirm(this.selectedCardId), null, false, 'red');
</pre>

=== Image Button ===

You can use the same method, but add extra class to a button to disable the padding and style it, i.e.
<pre>
this.addActionButton( 'button_brick', '<div class="brick"></div>', ()=>{... on brick ...}, null, null, 'gray');
dojo.addClass('button_brick','bgaimagebutton');
</pre>

where

<pre>
.bgaimagebutton {
padding: 0px 12px;
min-height: 28px;
border: none;
}
</pre>

If you use this a lot, you can define a helper function, i.e.
<pre>
/**
* This method can be used instead of addActionButton, to add a button which is an image (i.e. resource). Can be useful when player
* need to make a choice of resources or tokens.
*/
addImageActionButton: function(id, div, handler, bcolor, tooltip) {
if (typeof bcolor == "undefined") {
bcolor = "gray";
}
// this will actually make a transparent button id color = gray
this.addActionButton(id, div, handler, null, false, bcolor);
// remove border, for images it better without
dojo.style(id, "border", "none");
// but add shadow style (box-shadow, see css)
dojo.addClass(id, "shadow bgaimagebutton");
// you can also add additional styles, such as background
if (tooltip) {
dojo.attr(id, "title", tooltip);
}
return $(id);
},
</pre>

=== Disabling Button ===

You can disable the '''bgabutton''' by adding the css class '''disabled''' in you js. The disabled button is still visible but is grey and not clickable.
For example in the '''onUpdateActionButtons''' :
<pre>
this.addActionButton('play_button_id', _('Play 1 to 3 cards'), 'playFunctionButton');
if (condition) {
dojo.addClass('play_button_id', 'disabled');
}
</pre>

=== Custom Buttons ===

You can create a custom button, but the BGA framework provides a standard button that requires only .css classes: '''bgabutton''' and '''bgabutton_${color}'''.

'''Examples:'''

<pre>
<a href="#" id="my_button_id" class="bgabutton bgabutton_blue"><span>My blue button</span></a>

<a href="#" id="my_button_id" class="bgabutton bgabutton_red bgabutton_big"><span>My big red button</span></a>
</pre>

'''Note''': To see it in action, check out ''Coloretto''.

=== Button outside of action bar ===

Use addActionButton() method with destination argument set
<pre>
this.addActionButton( 'commit_button', _('Confirm'), 'onConfirm', 'player_board', true, 'red');
</pre>

in example above the button will be place on object with id 'player_board'

== Image loading ==

See also [[Game_art:_img_directory]].

'''Be careful''': by default, ALL images of your img directory are loaded on a player's browser when he loads the game. For this reason, don't let in your img directory images that are not useful, otherwise it's going to slowdown the game load.

'''this.dontPreloadImage(image_file_name: string)'''

Using dontPreloadImage, you tell the interface to not preload a specific image in your img directory.

Example of use:
<pre>
this.dontPreloadImage( 'cards.png' );
</pre>

This is particularly useful if for example you have 2 different themes for a game. To accelerate the loading of the game, you can specify to not preload images corresponding to the other theme.

Another example of use: in "Gosu" game with Kamakor extension, you play with 5 sets of cards among 10 available. Cards images are organized by sets, and we only preload the images corresponding to the 5 current sets with '''ensureSpecificGameImageLoading( image_file_names_array )'''.
<pre>
// By default, do not preload anything
this.dontPreloadImage( 'cards.png' );
this.dontPreloadImage( 'clan1.png' );
this.dontPreloadImage( 'clan2.png' );
this.dontPreloadImage( 'clan3.png' );
this.dontPreloadImage( 'clan4.png' );
this.dontPreloadImage( 'clan5.png' );
this.dontPreloadImage( 'clan6.png' );
this.dontPreloadImage( 'clan7.png' );
this.dontPreloadImage( 'clan8.png' );
this.dontPreloadImage( 'clan9.png' );
this.dontPreloadImage( 'clan10.png' );
var to_preload = [];
for( i in this.gamedatas.clans )
{
var clan_id = this.gamedatas.clans[i];
to_preload.push( 'clan'+clan_id+'.png' );
}

this.ensureSpecificGameImageLoading( to_preload );

</pre>

'''Note:''' You don't need to specify to not preload game box images (game_box.png, game_box75.png...) since they are not preloaded by default.

'''this.ensureSpecificGameImageLoading(list: string[])'''

This is oppostive of dontPreloadImage - its ensure specific images is loaded. Note: only makes sense if preload list is empty, otherwise everything is loaded anyway

'''load specific images'''
All images that will be preloaded stored in g_img_preload. If you want to override it directly - there is no API, but you can do this in GAME constructor

g_img_preload = ['tokens.png', 'trains.png', 'loc_plan.png', 'eng.png', 'eng-back.png'];

You can also set it to empty array and call ensureSpecificGameImageLoading() on specific images

== Sounds ==

Add a custom sound and make it load with your interface:

Add this in your template (.tpl) file:
<pre>
<audio id="audiosrc_<gamename>_<yoursoundname>" src="{GAMETHEMEURL}img/<gamename>_<yoursoundname>.mp3" preload="none" autobuffer></audio>
<audio id="audiosrc_o_<gamename>_<yoursoundname>" src="{GAMETHEMEURL}img/<gamename>_<yoursoundname>.ogg" preload="none" autobuffer></audio>
</pre>

Note: this is a requirement to provide both a mp3 and a ogg file with the names <code><gamename>_<yoursoundname>[.ogg][.mp3]</code>.

Play the sound (from your .js file):

<pre>
playSound('<gamename>_<yoursoundname>'); // do not add 'this.' - its a global function
</pre>

Disable the standard "move" sound for this move (to replace it with your custom sound):

Add this to your notification handler:

<pre>
this.disableNextMoveSound();
</pre>

Note: it only disable the sound for the next move.

== Title bar and states ==

=== Client states ===

Client states is a way to simulate the state transition but without actually going
to server. It is usefull when you need to ask user multiple questions before you
send things to server

'''this.setClientState(newState: string, args: object)'''

Example:
this.setClientState("client_playerPicksLocation", {
descriptionmyturn : _("${you} must select location"),
});

For more information see [[BGA_Studio_Cookbook#Multi_Step_Interactions:_Select_Worker.2FPlace_Worker_-_Using_Client_States]]

'''this.restoreServerGameState()'''
If you are in client state it will restore the current server state (cheap undo)

'''this.on_client_state'''
Boolean indicating that we are in client state

=== Title bar ===
If you simply want to show something in title bar you can do it directly
$('pagemaintitletext').innerHTML = text;

This however will not work with parameters and will not draw You in color,
if you want to do proper args rendering use method below

;'''this.removeActionButtons()'''
Removes all buttons from title bar

;'''this.updatePageTitle()'''
:This function allows to update the current page title and turn description according to the game state arguments. If the current game state description this.gamedatas.gamestate.descriptionmyturn is modified before calling this function it allows to update the turn description without changing state. This will handle arguments substitutions properly.

Note: this functional also will calls this.onUpdateActionButtons, if you want different buttons then state defaults, use method in example to replace them, if it becomes too clumsy use client states (see above)

Example from Terra Mystica:
<pre>
onClickFavorTile: function( evt ) {
...
if ( ... ) {
this.gamedatas.gamestate.descriptionmyturn = _('Special action: ') + _('Advance 1 space on a Cult track');
this.updatePageTitle();
this.removeActionButtons();
this.addActionButton( ... );
...
return;
}
...

}
</pre>

== User preferences ==
'''this.getGameUserPreference(pref_id)'''

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

'''this.setGameUserPreference(pref_id, value)'''

Programmatically change a user preference. It will have the same effect as if the player changed the value in the select combo box, in the top-right menu.

'''this.onGameUserPreferenceChanged'''

A callback you can define if you want to be notified when a user changes a user preference.

Example:<pre>
onGameUserPreferenceChanged: function(pref_id, pref_value) {
switch (pref_id) {
case 201:
document.getElementsByTagName('html')[0].classList.toggle('dark-background', pref_value == 2);
break;
}
}
</pre>

== Other useful stuff ==

'''dojo.hitch'''

With dojo.hitch, you can create a callback function that will run with your game object context whatever happen.

Typical example: display a BGA confirmation dialog with a callback function created with dojo.hitch:

<pre>
this.confirmationDialog( _('Are you sure you want to make this?'), dojo.hitch( this, function() {
this.bgaPerformAction('makeThis');
} ) );
</pre>

In the example above, using dojo.hitch, we ensure that the "this" object will be set when the callback is called.

NOTE: In modern JS there are lambdas that eliminate need for that, the example above will look like this
<pre>
this.confirmationDialog( _('Are you sure you want to make this?'), () => this.bgaPerformAction( 'makeThis') );
</pre>

;'''onScreenWidthChange()'''
:This function can be overridden in your game to manage some resizing on the client side when the browser window is resized. This function is also triggered at load time, so it can be used to adapt to the :viewport size at the start of the game too.

; this.bRealtime
: Return true if the game is in realtime. Note that having a distinct behavior in realtime and turn-based should be exceptional.

; g_replayFrom
: Global contains replay number in live game, it is set to undefined (i.e. not set) when it is not a replay mode, so consequentially the good check is '''typeof g_replayFrom != 'undefined'''' which returns true if the game is in replay mode <i>during the game</i> (the game is ongoing but the user clicked "replay from this move" in the log)

; g_archive_mode
: Returns true if the game is in archive mode <i>after the game</i> (the game has ended)

; this.instantaneousMode
: Returns true during replay/archive mode if animations should be skipped. Only needed if you are doing custom animations. (The BGA-provided animation functions like <i>this.slideToObject()</i> automatically handle instantaneous mode.)
: Technically, when you click "replay from move #20", the system replays the game from the very beginning with moves 0 - 19 happening in instantaneous mode and moves 20+ happening in normal mode.

; g_tutorialwritten
: Returns an object like the below if the game is in tutorial mode, or undefined otherwise. Tutorial mode is a special case of archive mode where comments have been added to a previous game to teach new players the rules.
{
author: "91577332",
id: "576",
mode: "view"
status: "alpha"
version_override: null
viewer_id: "84554161"
}

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

[[Category:Studio]]

Game interface logic: Game.js

2024-09-25T17:49:26Z

Sguzzer Gunayer: /* Sliding */

{{Studio_Framework_Navigation}}

__TOC__

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

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

== File structure ==

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

Here is the basic structure:

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

More details:

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

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

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

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

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

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

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

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

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

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

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

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

== Dojo framework ==

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

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

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

== Javascript minimization (after July 2020) ==

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

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

== Accessing Players Information ==

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

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

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

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

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

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

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

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

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

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

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

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

== Accessing and manipulating the DOM ==

=== Element by Id ===

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

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

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

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

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

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

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

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

=== Style ===

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

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

Examples:

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

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

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

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

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

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

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

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

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

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

=== Classes ===

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

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

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

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

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

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

Example from ''Reversi'':

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

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

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

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

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

'''Vanilla JS classList'''

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

=== Attributes ===

;dojo.attr

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

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

'''Vanilla JS attr'''

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

=== Queries ===

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

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

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

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

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

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

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

'''Vanilla JS query'''

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

=== Creating and Destroying elements ===

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

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

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

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

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

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

Create element

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

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

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

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

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

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

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

const div = ``;
'''this.format_string_recursive'''

This bga function is similar to this.format_string but is capable of processing recursive argument structures and translations. It is used to format server notifications.

TODO: find better place for these function docs

=== Moving elements ===

'''dojo.place(node: string | Element, refNode: ElementOrId, pos?: string | number): Element'''

dojo.place is the best function to insert HTML code somewhere in your game interface without breaking something. It is much better to use than the '''innerHTML=''' method if you must insert HTML tags and not only values.

node: can be a string or a DOM node. If it is a string starting with “<”, it is assumed to be an HTML fragment, which will be created. Otherwise it is assumed to be an id of a DOM node.

<pre>
// Insert your HTML code as a child of a container element
dojo.place( "<div class='foo'></div>", "your_container_element_id" );
</pre>

pos: optional argument. Can be a number or one of the following strings: “before”, “after”, “replace”, “only”, “first”, or “last”. If omitted, “last” is assumed.

* "replace": replace the container element with my_node element
* "first": places the node as a child of the reference node. The node is placed as the first child.
* "last" (default): places the node as a child of the reference node. The node is placed as the last child.
* "before": places the node right before the reference node.
* "after": places the node right after the reference node.
* "only": replaces all children of the reference node with the node.

this parameter can be a positive integer. In this case, the node will be placed as a child of the reference node with this number (counting from 0). If the number is more than number of children, the node will be appended to the reference node making it the last child.

<pre>
// Replace all children of container with my_node
dojo.place( $('my_node'), "your_container_element_id", "only" );
</pre>

See also full doc on dojo.place: [https://dojotoolkit.org/reference-guide/1.7/dojo/place.html]

Usually, when you want to insert some piece of HTML in your game interface, you should use "[[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl#Javascript_templates|Javascript templates]]".

But you can also relocate elements like that. Note: it won't animate if you do that.

'''this.placeOnObject(mobile_obj: ElementOrId, target_obj: ElementOrId): void'''

places mobile_obj on target_obj, set the absolute positions and centers the mobile_obj on target_obj,
effect is immediate

This is not really an animation, but placeOnObject is frequently used before starting an animation.

Example:
<pre>
// (We just created an object "my_new_token")

// Place the new token on current player board
this.placeOnObject( "my_new_token", "overall_player_board_"+this.player_id );

// Then slide it to its position on the board
this.slideToObject( "my_new_token", "a_place_on_board" ).play();
</pre>

'''this.placeOnObjectPos(mobile_obj: ElementOrId, target_obj: ElementOrId, target_x: number, target_y: number): void'''

This method works exactly like placeOnObject, except than you can specify some (x,y) coordinates (in px). This way, the center of "mobile_obj" will be placed to the specified x,y position relatively to the center of "target_obj".

''Note: the placement works differently from this.slideToObjectPos'', since coordinates are calculated based on the center of objects.

'''this.attachToNewParent(mobile_obj: ElementOrId, target_obj: ElementOrId): void'''

With this method, you change the HTML parent of "mobile_obj" element without moving it.
"target_obj" is the new parent of this element. The beauty of
attachToNewParent is that the mobile_obj element DOES NOT MOVE during this process.

What happens is that the method calculate a relative position of mobile_obj to make sure it does not move after the HTML parent changes.

Why using this method?

Changing the HTML parent of an element can be useful for the following reasons:
* When the HTML parent moves, all its child are moving with them. If some game elements is no more linked with a parent HTML object, you may want to attach it to another place.
* The z_order (vertical order of display) depends on the position in the DOM, so you may need to change the parent of some game elements when they are moving in your game area.

'''CAREFUL''': this function destroys original object and places a clone onto a new parent, this will break all references to this HTML element (ex: dojo.connect).
If you need version that does not destroy the object but the same otherwise see [[BGA_Studio_Cookbook#Attach_to_new_parent_without_destroying_the_object]]

== Animations ==

===Dojo Animations===

BGA animations is based on Dojo Animation ([http://dojotoolkit.org/documentation/tutorials/1.8/animation/ see tutorial here]).

However, most of the time, you can just use methods below, which are built on top of Dojo Animation.

Note: one interesting method from Dojo that could be useful from time to time is "Dojo.Animation". It allows you to make any CSS property "slide" from one value to another.

Note 2: the slideTo methods are not compatible with CSS transform (scale, zoom, rotate...). If possible, avoid using CSS transform on nodes that are being slided. Eventually, the only possible solution to make these 2 compatible is to disable all CSS transform properties, use slideToObjectPos/placeOnObjectPos, and then apply them again.

===Sliding===

'''this.slideToObject(mobile_obj: ElementOrId, target_obj: ElementOrId, duration?: number, delay?: number): Animation'''

You can use slideToObject to "slide" an element to a target position.

Sliding element on the game area is the recommended and the most used way to animate your game interface. Using slides allow players to figure out what is happening on the game, as if they were playing with the real boardgame.

The parameters are:
* mobile_obj: the ID of the object to move. This object must be "relative" or "absolute" positioned.
* target_obj: the ID of the target object. This object must be "relative" or "absolute" positioned. Note that it is not mandatory that mobile_obj and target_obj have the same size. If their size are different, the system slides the center of mobile_obj to the center of target_obj.
* duration: (optional) defines the duration in millisecond of the slide. The default is 500 milliseconds.
* delay: (optional). If you defines a delay, the slide will start only after this delay. This is particularly useful when you want to slide several object from the same position to the same position: you can give a 0ms delay to the first object, a 100ms delay to the second one, a 200ms delay to the third one, ... this way they won't be superposed during the slide.

BE CAREFUL: The method returns an dojo.fx animation, so you can combine it with other animation if you want to. It means that you have to call the "play()" method, otherwise the animation WON'T START.

Example:
<pre>
this.slideToObject( "some_token", "some_place_on_board" ).play();
</pre>

'''this.slideToObjectPos(mobile_obj: ElementOrId, target_obj: ElementOrId, target_x: number, target_y: number, duration?: number, delay?: number): Animation'''

This method does exactly the same as "slideToObject", except than you can specify some (x,y) coordinates. This way, "mobile_obj" will slide to the specified x,y position relatively to "target_obj".

Example: slide a token to some place on the board, 10 pixels from the top:
<pre>
this.slideToObjectPos( "some_token", "some_place_on_board", 0, 10 ).play();
</pre>

'''this.slideTemporaryObject(mobile_obj_html: string, parent: ElementOrId, from: ElementOrId, to: ElementOrId, duration?: number, delay?: number): Animation'''

This method is useful when you want to slide a temporary HTML object from one place to another. As this object does not exists before the animation and won't remain after, it could be complex to create this object (with dojo.place), to place it at its origin (with placeOnObject) to slide it (with slideToObject) and to make it disappear at the end.

slideTemporaryObject does all of this for you:
* mobile_obj_html is a piece of HTML code that represent the object to slide.
* parent is the ID of an HTML element of your interface that will be the parent of this temporary HTML object.
* from is the ID of the origin of the slide.
* to is the ID of the target of the slide.
* duration/delay works exactly like in "slideToObject"

Example:
<pre>
this.slideTemporaryObject( '<div class="token_icon"></div>', 'tokens', 'my_origin_div', 'my_target_div' ).play();
</pre>

===Destroy===
'''this.slideToObjectAndDestroy(mobile_obj: ElementOrId, target_obj: ElementOrId, duration?: number, delay?: number): void'''

This method is a handy shortcut to slide an existing HTML object to some place then destroy it upon arrival. It can be used for example to move a victory token or a card from the board to the player panel to show that the player earns it, then destroy it when we don't need to keep it visible on the player panel.

It works the same as this.slideToObject and takes the same arguments, but it starts the animation.

CAREFUL: Make sure nothing is creating the same object at the same time the animation is running, because this will cause some random disappearing effects

Example:
<pre>
this.slideToObjectAndDestroy( "some_token", "some_place_on_board", 1000, 0 );
</pre>

'''this.fadeOutAndDestroy( node: string | Element, duration?: number, delay?: number):''' '''void'''

This function fade out the target node, then destroy it. Its starts the animation.
* duration/delay works exactly like in "slideToObject"

Example:
<pre>
this.fadeOutAndDestroy( "a_card_that_must_disappear" );
</pre>

CAREFUL: the HTML node still exists until during few milliseconds, until the fadeOut has been completed.
Make sure nothing is creating same object at the same time as animation is running, because you will be some random dissapearing effects

===Rotating elements===

This example combines "Dojo.Animation" method and a CSS property transform that allow you to rotate the element.
<pre>
// node is Element we rotating
var animation = new dojo.Animation({
curve: [fromDegree, toDegree],
onAnimate: (v) => {
node.style.transform = 'rotate(' + v + 'deg)';
}
});

animation.play();
</pre>

BGA has its own interface to rotate

'''this.rotateTo(node: string | Element, degree: number): void'''

It starts the animation, and stored the rotation degree in the class, so next time you rotate object - it is additive.
There is no animation hooks in this one, if you need to change any parameters use dojo animation above.

There is also '''rotateInstantTo''' with same signature which does not animate

===Animation Callbacks===

If you wish to run some code only after an animation has completed you can do this by linking a callback method to 'onEnd'.

<pre>
var animation_id = this.slideToObject( mobile_obj, target_obj, 500 );
dojo.connect(animation_id, 'onEnd', () => {
// do something here
});
animation_id.play();
</pre>

If you wish to call a second animation after the first (rather than general code) then you can use a dojo animation chain (see tutorial referenced above).

== Players input ==

=== Connecting ===
'''dojo.connect(element: Element, event: string, context: object, method: eventHandler): any'''

'''dojo.connect(element: Element, event: string, hander: eventHandler): any'''

Used to associate a player event with one of your notification methods.

Example: associate a click on an element ("my_element") with one of our methods ("onClickOnMyElement"):
<pre>
dojo.connect( $('my_element'), 'onclick', this, 'onClickOnMyElement' );
</pre>

Same idea but base on query (i.e. all element of 'pet' class)
dojo.query(".pet").connect('onclick', this, 'onPet');

Note: if you need to disconnect the handler you have to store handler returned from this method, i.e.

<pre>
var handler = dojo.connect(...);
...
dojo.disconnect(handler);
</pre>

If you don't store the handler - you have to destroy the object to disconnect it

Typical function that implements the input handler will look like this

<pre>
onPet: function(event) {
var id = event.currentTarget.id;
console.log('onPet ' + id);
dojo.stopEvent(event);
if (this.gamedatas.gamestate.name == 'playerTurnPet') {
this.bgaPerformAction('actPlayPet', {card: id});
} else {
this.showMoveUnauthorized();
}
}
</pre>

'''this.connect(element: ElementOrId, event: string, method: eventHandler): void'''

Used to associate a player event with one of your notification methods.

this.connect( $('my_element'), 'onclick', 'onClickOnMyElement' );

Or you can use an in-place handler

this.connect( $('my_element'), 'onclick', (e) => { console.log('boo'); } );

Note that this function stores the connection handler. That is the only real difference between '''this.connect''' and '''dojo.connect'''. If you plan to destroy the element you connected, you '''must''' call this.disconnect() to prevent memory leaks.
This function is mainly for permanent objects - if you just want to connect the temp object you should probably not use this method but use dojo.connect which won't require any clean-up.

'''this.connectClass(cssClassName: string, event: string, method: eventHandler): void'''

Same as connect(), but for all the nodes set with the specified cssClassName.

this.connectClass('pet', 'onclick', 'onPet');

'''this.disconnect(element: ElementOrId, event: string): void'''

Disconnect event handler (previously registered with this.connect or this.connectClass).

this.disconnect( $('my_element'), 'onclick');

Note: dynamic connect/disconnect is for advanced cases ONLY, you should always connect elements statically if possible, i.e. in setup() method.

'''this.disconnectAll(): void'''

Disconnect all previously registed event handlers (registered via this.connect or this.connectClass)

this.disconnectAll();

=== Actions ===

'''this.bgaPerformAction(action: string, args?: object, options: object = { lock: true, checkAction: true }): Promise<void>'''

Triggers an action on the backend. This is a combination of checkAction and ajaxcall, returning a Promise which resoves when ajaxcall ends.

This method must be used to send a player input to the game server. '''It should not be triggered programmatically''', especially not in loops, in callbacks, in notifications, or in onEnteringState/onUpdateActionButtons/onLeavingState, in order not to create race conditions or break replay game and tutorial features. It should be used only in reaction to a user action in the interface.

* action: name of the action, as it is written in "possibleactions" of the current state.
* args: an object containing the call parameters to send to the action
* options: options to tweak the call with some defaults. Default is <code>{ lock: true, checkAction: true }</code>.

Example of a standard call without args:
this.bgaPerformAction('pass');

Example of a standard call with action args:
this.bgaPerformAction('actPlayCard', { id: this.selectedCardId });

Example of a call without checking action (because player is inactive in a multiactive state):

this.bgaPerformAction('actChangeMind', {}, { checkAction: false });

Example of a call without lock (because of a special action not directly related to the game flow):

this.bgaPerformAction('actSetAutoBid', { alwaysBidUntil: 500 }, { lock: false, checkAction: false });

Example of call with reaction to exception:
this.bgaPerformAction('actPlayCard', { id: this.selectedCardId }).catch(()=>{ this.selectedCardId = undefined; });

Example of call with reaction to success:
this.bgaPerformAction('actPlayCard', { id: this.selectedCardId }).then(()=>{ this.unselectAll(); });

'''this.ajaxcall(url, parameters, obj_callback, callback, callback_anycase?, ajax_method?: string)'''

''Note: bgaPerformAction is a simpler way to use ajax calls, ajaxcall stays in the doc for legacy reasons only and should not be used in new projects.''

Same warning as '''this.bgaPerformAction''' about using on user action only.

* url: the url of the action to perform. For a game, it must be: "/<mygame>/<mygame>/myAction.html"
* parameters: an array of parameter to send to the game server.
** Note that "lock: true" must always be specified in this list of parameters in order the interface can be locked during the server call. Cannot use lock: false - to not lock it has to be undefined.
** Note: Restricted parameter names (please don't use them):
*** "action"
*** "module"
*** "class"
* obj_callback: must be set to "this".
* callback (non-optional but rarely used): a function to trigger when the server returns result and everything went fine (not used, as all data handling is done via notifications).
* callback_anycase: (optional) a function to trigger when the server returns ok OR error. If no error this function is called with parameter value false. If an error occurred, the first parameter will be set to true, the second will contain the error message sent by the PHP back-end, and the third will contain an error code.
* ajax_method: (optional and rarely used) if you need to send large amounts of data (over 2048 bytes), you can set this parameter to 'post' (all lower-case) to send a POST request as opposed to the default GET. This works, but was not officially documented, so only use if you really need to.

Usage:
<pre>
this.ajaxcall( '/mygame/mygame/actMyAction.html', { lock: true,
arg1: myarg1,
arg2: myarg2
}, this, (result)=>{} );
</pre>

'''this.checkAction(action: string, nomessage?: boolean): boolean '''

Check if player can do the specified action by taking into account:
* if interface is locked it will return false and show message "An action is already in progress", unless nomessage set to true
* if player is not active it will return false and show message "This is not your turn", unless nomessage set to true
* if action is not in list in possible actions (defined by "possibleaction" in current game state) it will return false and show "This move is not authorized now" error (unconditionally).
* otherwise returns true
Example:
<pre>
function onClickOnGameElement( evt ) {
if( this.checkAction( "actMyAction" ) ) {
// Do the action
}
}
</pre>

'''this.checkPossibleActions(action: string): boolean'''

* this is independent of the player being active, so can be used instead of this.checkAction(). This is particularly useful for multiplayer states when the player is not active in a 'player may like to change their mind' scenario. Unlike this.checkAction, this function does NOT take interface locking into account

* if action is not in list in possible actions (defined by "possibleaction" in current game state) it will return false and show "This move is not authorized now" error (unconditionally).
* otherwise returns true

function onChangeMyMind( evt ) {
if( this.checkPossibleActions( "actMyAction" ) ) {
// Do the action
}
}

'''this.checkLock(nomessage?: boolean): boolean'''

When using "lock: true" in ajax call you can use this function to check if interface is in lock state (it will be locked during server call and notification processing).
This check can be used to block some other interactions which do not result in ajaxcall or if you want to suppress errors. Note: normally you only need to use this.checkAction(...), this is for advanced cases.

It will also show error unless nomessage is set to true

function onChangeMyMind( evt ) {
if( this.checkLock() ) {
// Do the action
}
}

== Notifications ==

When something happens on the server side, your game interface Javascript logic received a notification.
If you have not done so yet check what notification are in [[Main_game_logic:_yourgamename.game.php#Notifications]]

Here's how you can handle these notifications on the client side.

=== Subscribe to notifications ===

'''dojo.subscribe(notif_type: string, callback_obj: Object, handler: string|handler)'''
* notif_type - notification type/name send by php server
* callback_obj - usually this
* handler - if string method of callback_obj with name name is called, when notification is called, with notification object as parameter (see below)

Your Javascript "setupNotifications" method is the place where you can subscribe to notifications from your PHP code.

Here's how you associate one of your Javascript method to a notification "playDisc" (from Reversi example):

<pre>
setupNotifications: function() {
...
dojo.subscribe('playDisc', this, "notif_playDisc");
},
</pre>

Note: the "playDisc" corresponds to the name of the notification you define it in your PHP code, in your "notifyAllPlayers" or "notifyPlayer" method.

Then, you have to define your "notif_playDisc" method:

<pre>
notif_playDisc: function(notif) {
// Remove current possible moves (makes the board more clear)
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );
this.addDiscOnBoard( notif.args.x, notif.args.y, notif.args.player_id );
},
</pre>

In a notification handler like our "notif_playDisc" method, you can access all notifications arguments with "notif.args".

Example:

PHP

<pre>
$this->notifyAllPlayers( "apples", clienttranslate('player takes ${count} apples'), [ "count" => 3 ] );
</pre>

JavaScript

<pre>
setupNotifications: function() {
dojo.subscribe( 'apples', this, 'notif_apples' );
},

notif_apples: function(notif) {
//You can access the "count" like this:
alert("count = " + notif.args.count);
}
</pre>

=== The notification Object received by client ===

When sending a notification on your PHP, the client side will receive an Object with the following attributes:

* type - type of the notification (as passed by php function)
* log - the log string passed from php notification
* args - This is the arguments that you passed on your notification method on php
* bIsTableMsg - is true when you use [[Main_game_logic:_yourgamename.game.php#NotifyAllPlayers|NotifyAllPlayers]] method (false otherwise)
* channelorig - information about table ID (formatted as : "/table/t[TABLE_NUMBER]")
* gamenameorig - name of the game
* move_id - ID of the move associated with the notification
* table_id - ID of the table (comes as string)
* time - UNIX GMT timestamp
* uid - unique identifier of the notification
* h - unknown

'' Note that those information were inferred from observation on console log. If an Admin can confirm/correct (and remove this line), you're welcome :)''

=== Ignoring notifications ===

Sometimes you need to ignore some notification on client side. You don't want them to be shown in game log and you don't want them to be handled.

The most common use case is when a player gets private information. They will receive a specific notification (such as "You received Ace of Heart"), while other players would receive more generic notification ("Player received a card").

In X.game.php
<pre>
$this->notifyAllPlayers("dealCard", clienttranslate('${player_name} received a card'), [
'player_id' => $playerId,
'player_name' => $this->getActivePlayerName()
]);

$this->notifyPlayer($playerId, "dealCardPrivate", clienttranslate('You received ${cardName}'), [
"type" => $card["type"],
"cardName" => $this->getCardName($card["type"])
]);
</pre>

The problem with this approach is that the active player will receive two notifications:
* Player1 received a card
* You received Ace of Hearts

Hence, notification ignoring.

NOTE: You can think that it would be possible to send such notification to all players except active just by using notifyPlayer and it seems to work. The problem however is that table spectators would miss such notification and their user interface (and game log) wouldn't be updated. Since there is no way to send notification just to spectators, ignoring the notification (or "filtering") is the only reasonable solution.

'''setIgnoreNotificationCheck(notif_type: string, predicate: ((notif: Notif)=>boolean))'''
This method will set a check whether any of notifications of specific type should be ignored.

The parameters are:
* notif_type: type of the notification
* predicate (notif => boolean): a function that will receive notif object and will return true if this specific notification should be ignored

Before dispatching any notification of this type, the framework will call predicate to check whether notification should be ignored, if it return true - the notification will be dispatched, i.e. logged or handled.

<pre>
this.notifqueue.setIgnoreNotificationCheck( 'dealCard', (notif) => (notif.args.player_id == this.player_id) );
</pre>

IMPORTANT: Remember that this notification is ignored on the client side, but was still received by the client. Therefore it shouldn't contain any private information as cheaters can get it. In other words this is not a way to hide information.

IMPORTANT: When a game is reloaded with F5 or when opening a turn based game, old notifications are replayed as history notification. They are used just to update the game log and are stripped of all arguments except player_id, i18n and any argument present in message. If you use and other argument in your predicate you should '''preserve''' it as explained [[Main_game_logic:_yourgamename.game.php#Notify_players|here]].

=== Synchronous notifications ===

When several notifications are received by your game interface, these notifications are processed immediately, one after the other, in the same exact order they have been generated in your PHP game logic.

However, sometimes, you need to give some time to the players to figure out what happened on the game before jumping to the next notification. Indeed, in many games, there are a lot of automatic actions, and the computer is going to resolve all these actions very fast if you don't tell it not to do so.

As an example, for Reversi, when someone is playing a disc, we want to wait 500 milliseconds before doing anything else in order the opponent player can figure out what move has been played.

Here's how we do this, right after our subscription:
<pre>
dojo.subscribe( 'playDisc', this, "notif_playDisc" );
this.notifqueue.setSynchronous( 'playDisc', 500 ); // Wait 500 milliseconds after executing the playDisc handler
</pre>

-----

It is also possible to control the delay timing dynamically (e.g., using notification args). As an example, maybe your notification 'cardPlayed' should pause for a different amount of time depending on the number or type of cards played.

For this case, use '''setSynchronous''' without specifying the duration and use '''setSynchronousDuration''' within the notification callback.

* NOTE: If you forget to invoke '''setSynchronousDuration''', the game will remain paused forever!

<pre>
setupNotifications: function () {
dojo.subscribe( 'cardPlayed', this, 'notif_cardPlayed' );
this.notifqueue.setSynchronous( 'cardPlayed' ); // wait time is dynamic
...
},

notif_cardPlayed: function (notif) {
// MUST call setSynchronousDuration

// Example 1: From notification args (PHP)
this.notifqueue.setSynchronousDuration(notif.args.duration);
...

// Or, example 2: Match the duration to a Dojo animation
var anim = dojo.fx.combine([
...
]);
anim.play();
this.notifqueue.setSynchronousDuration(anim.duration);
},
</pre>

You can also manually call this.notifqueue.setSynchronousDuration(0) once client operations are finished, but be careful that even fast replay still has a path to call it.

'''WARNING: combining synchronous and ignored notifications'''
You must be careful when combining dynamic synchronous durations (as described above) with ignored notifications. If you have a conditionally ignored notification like this (see below section):

<pre>this.notifqueue.setIgnoreNotificationCheck( 'myNotif', (notif) => (notif.args.player_id == this.player_id) /* or any other condition */ )</pre>

then you CANNOT do

<pre>this.notifqueue.setSynchronous('myNotif');</pre>

as, when the ignored check passes, the notification handler, in which `this.notifqueue.setSychronousDuration` is called, is never called and so the duration is never set and interface locking results.

The workaround is to set a "dummy" time:

<pre>this.notifqueue.setSynchronous('myNotif', 5000);</pre>

whose value is irrelevant but must be large enough to cover the time before the notification handler is called. The large value never actually comes into play because the notification is either ignored, or the synchronous duration is reset to a sensible value inside the handler.

=== Pre-defined notification types ===

'''tableWindow''' - This defines notification to display [[Game_interface_logic:_yourgamename.js#Scoring_dialogs|Scoring Dialogs]], see below.

'''message''' - This defines notification that shows on players log and have no other effect (technically any unhandled notification will do the same but its recommended to use this keyword for consistency)

// You can call this on php side without doing anything on client side
self::notifyAllPlayers( 'message', clienttranslate('hello'), [] );

'''simplePause''' - This notification will just delay other notifications, maybe useful if you know you need some extra time for animation or something. Requires a time parameter.

<pre>
self::notifyAllPlayers( 'simplePause', '', [ 'time' => 500] ); // time is in milliseconds
</pre>

Note: the following types are RESERVED by framework, do not use:

gameStateChange gameStateChangePrivateArg gameStateMultipleActiveUpdate newActivePlayer playerstatus yourturnack clockalert tableInfosChanged playerEliminated tableDecision archivewaitingdelay end_archivewaitingdelay replaywaitingdelay end_replaywaitingdelay replayinitialwaitingdelay end_replayinitialwaitingdelay aiPlayerWaitingDelay replay_has_ended updateSpectatorList wouldlikethink updateReflexionTime undoRestorePoint resetInterfaceWithAllDatas zombieModeFail zombieModeFailWarning aiError skipTurnOfPlayer zombieBack allPlayersAreZombie gameResultNeutralized playerConcedeGame showTutorial showCursor showCursorClick skipTurnOfPlayerWarning banFromTable resultsAvailable switchToTurnbased newPrivateState infomsg

== Tooltips ==

=== Adding static tooltips ===

'''this.addTooltip(nodeId: string, helpStringTranslated: string, actionStringTranslated: string, delay?: number): void'''

Add a simple text tooltip to the DOM node.

Specify 'helpStringTranslated' to display some information about "what is this game element?".
Specify 'actionStringTranslated' to display some information about "what happens when I click on this element?".

You must specify both of the strings. You can only use one and specify an empty string ('') for the other one.

When you pass text directly function _() must be used for the text to be marked for translation! Except for empty string.

Parameter "delay" is optional. It is primarily used to specify a zero delay for some game element when the tooltip gives really important information for the game - but remember: no essential information must be placed in tooltips as they won't be displayed in some browsers (see [[BGA_Studio_Guidelines|Guidelines]]).

Example:
<pre>
this.addTooltip( 'cardcount', _('Number of cards in hand'), '' );
</pre>

Note: this generates static tooltip and attaches to existing dom element, if you need to generate tooltip more dynamically you have to call that method every time information about object is updated or use completely different tehnique, see dynamic tooltips below.

'''this.addTooltipHtml(nodeId: string, html: string, delay?: number): void'''

Add an HTML tooltip to the DOM node (for more elaborate content such as presenting a bigger version of a card).

'''this.addTooltipToClass(cssClass: string, helpStringTranslated: string, actionStringTranslated: string, delay?: number ): void'''

Add a simple text tooltip to all the DOM nodes set with this cssClass. See more details above for this.addTooltip.
this.addTooltipToClass( 'meeple', _('This is A Meeple'), _('Click to tickle') );

IMPORTANT: all concerned nodes must exist and have IDs to get tooltips.

'''this.addTooltipHtmlToClass(cssClass: string, html: string, delay?: number): void'''

Add an HTML tooltip to to all the DOM nodes set with this cssClass (for more elaborate content such as presenting a bigger version of a card).

IMPORTANT: all concerned nodes must exist and have IDs to get tooltips.

=== Removing static tooltips ===

'''this.removeTooltip(nodeId: string): void'''

Remove a tooltip from the DOM node with given id.

=== Advanced tooltips ===

'''force tooltip to open'''

If you want to force tooltip to open in reaction to some other action, i.e. click you can do this

this.tooltips[id].open(id)

where id is the id of the tooltip node where tooltip was installed.

'''dynamic tooltips'''

See [[BGA_Studio_Cookbook#Dynamic_tooltips]]

'''tooltips on mobile'''

Tooltips is very unreliable on mobile, it is recommended to implement some other method to obtaining same information,
such as simple click handler in dedicated "Help" mode or provide dedicated clickable areas such as corner of card.

== Warning messages ==

Sometimes, there is something important that is happening in the game and you have to make sure all players get the message. Most of the time, the evolution of the game situation or the game log is enough, but sometimes you need something more visible.

Ex: someone fulfills one of the end of the game conditions, so this is the last turn.

'''this.showMessage(msg: string, type: string): void'''

showMessage shows a message in a big rectangular area on the top of the screen of the current player, and it dissapears after few seconds (also it will be in the log in some cases).

* "msg" is the string to display. It should be translated.
* "type" can be set to "info", "error", "only_to_log" or custom string. If set to "info", the message will be an informative message on a white background. If set to "error", the message will be an error message on a red background and it will be added to log. If set to "only_to_log", the message will be added to the game log but will not popup at the top of the screen.
If set to custom string, it will be transparent, to use custom type define "head_xxx" in css, where xxx is the type. For example if you want yellow warning, use "warning" as type and add this to css:
.head_warning {
background-color: #e6c66e;
}

Important: the normal way to inform players about the progression of the game is the game log. The "showMessage" is intrusive and should not be used often.

<pre>
notif_messageinfo: function(notif) {
if (!g_archive_mode) {
var message = this.format_string_recursive(notif.log, notif.args);
this.showMessage(_('Announcement:') + " " + message, 'info');
}
},
</pre>

Show message could be used on the client side to prevent user wrong moves before it is send to server.
Example from 'battleship':
<pre>
onGrid: function(event) {
if (checkIfPlayerTriesToFireOnThemselves(event)) {
this.showMessage(_('This is your own board silly!'), 'error');
return;
}
...
},
</pre>

'''this.showMoveUnauthorized(): void'''

Shows predefined user error that move is unauthorized now

<pre>
onPet: function(event) {
if (checkPet(event)==false) {
this.showMoveUnauthorized();
return;
}
...
},
</pre>

== Dialogs ==

=== Confirmation dialog ===

When an important action with a lot of consequences is triggered by the player, you may want to propose a confirmation dialog.

CAREFUL: the general guideline of BGA is to AVOID the use of confirmation dialogs. Confirmation dialogs slow down the game and bother players. The players know that they have to pay attention to each move when they are playing online.

The situations where you should use a confirmation dialog are the following:
* It must not happen very often during a game.
* It must be linked to an action that can really "kill a game" if the player does not pay attention.
* It must be something that can be done by mistake (ex: a link on the action status bar).

'''this.confirmationDialog(message: string, yesHandler: (param: any) => void, noHandler?: (param: any) => void, param?: any): void'''

* message - message will be shown to user, use _() to translate
* yesHandler - non-optional handler to be called on yes
* noHandler - optional handler to called on no
* param - if specified, it will be passed to both handlers
NOTE: this is async function, it does not return anything and you should not do anything after, you must do everything in handlers

How to display a confirmation dialog:
<pre>
this.confirmationDialog(_("Are you sure you want to bake a pie?"), () => {
this.bakeThePie();
});
return; // nothing should be called or done after calling this, all action must be done in the handler
</pre>
With param and both handlers
<pre>
this.confirmationDialog(_("Are you sure you want to bake a pie?"),
(ingredient) => this.bakeThePie(ingredient),
(ingredient) => console.log(`cancelled baking of ${ingredient}`),
'apple');
</pre>

=== Multiple choice dialog ===

You can use this dialog to give user a choice with small amount of options

'''this.multipleChoiceDialog(message: string, choices: string[], callback: (choice: number) => void): void'''
* message - message will be shown to user, use _() to translate
* choices - array of choices
* callback - non-optional handler to be called on choice made, the choice parameter is the INDEX of the choice from the array of choices

NOTE: this is async function, it does not return anything and you should not do anything after, you must do everything in handlers
NOTE: there is no cancel handler, so make sure you gave user a choice to get out of it

Example:
<pre>
const keys = ["0", "1", "5", "10"];
this.multipleChoiceDialog(_("How many bugs to fix?"), keys, (choice) => {
if (choice==0) return; // cancel operation, do not call server action
var bugchoice = keys[choice]; // choice will be 0,1,2,3 here
this.bgaPerformAction("fixBugs", { number: bugchoice });
});
return; // must return here
</pre>

=== Generic Dialogs ===

As a general rule, you shouldn't use dialogs windows.

BGA guidelines specify that all game elements should be displayed on the main screen. Players can eventually scroll down to see game elements they don't need to see anytime, and you may eventually create anchors to move between game area section. Of course dialogs windows are very practical, but the thing is: all players know how to scroll down, and not all players know how to show up your dialog window. In addition, when the dialog shows up, players can't access the other game components.

Sometimes although, you need to display a dialog window. Here is how you do this:

// Create the new dialog over the play zone. You should store the handler in a member variable to access it later
this.myDlg = new ebg.popindialog();
this.myDlg.create( 'myDialogUniqueId' );
this.myDlg.setTitle( _("my dialog title to translate") );
this.myDlg.setMaxWidth( 500 ); // Optional

// Create the HTML of my dialog.
// The best practice here is to use [[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl#Javascript_templates|Javascript templates]]
var html = this.format_block( 'jstpl_myDialogTemplate', {
arg1: myArg1,
arg2: myArg2,
...
} );

// Show the dialog
this.myDlg.setContent( html ); // Must be set before calling show() so that the size of the content is defined before positioning the dialog
this.myDlg.show();

// Now that the dialog has been displayed, you can connect your method to some dialog elements
// Example, if you have an "OK" button in the HTML of your dialog:
dojo.connect($('my_ok_button'), 'onclick', this, (event) => {
event.preventDefault();
this.myDlg.destroy();
});

If necessary, you can remove the default top right corner 'close' icon, or replace the function called when it is clicked:
// Removes the default close icon
this.myDlg.hideCloseIcon();

// Replace the function call when it's clicked
this.myDlg.replaceCloseCallback((event) => { ... });

=== Scoring dialogs ===

Sometimes at the end of a round you want to display a big table that details the points wins in each section of the game.

Example: in Hearts game, we display at the end of each round the number of "heart" cards collected by each player, the player who collected the Queen of Spades, and the total number of points loose by each player.

Scoring dialogs are managed entirely on '''PHP side''', but they are described here as their effects are visible only on client side.

Displaying a scoring dialog is quite simple and is using a special notification type: "tableWindow":
<pre>
// on PHP side:
$this->notifyAllPlayers( "tableWindow", '', array(
"id" => 'finalScoring',
"title" => clienttranslate("Title of the scoring dialog"),
"table" => $table
));
</pre>

The "table" argument is a 2 dimensional PHP array that describes the table you want to display, line by line and column by column.

Example: display an 3x3 array of strings
<pre>
$table = [
[ "one", "two", "three" ], // This is my first line
[ "four", "five", "six" ], // This is my second line
[ "seven", "height", "nine" ] // This is my third line
];
</pre>

As you can see above, in each "cell" of your array you can display a simple string value. But you can also display a complex value with a template and associated arguments like this:
<pre>
$table = [
[ "one", "two", [ "str" => clienttranslate("a string with an ${argument}"), "args" => [ 'argument' => 'argument_value' ] ] ],
[ "four", "five", "six" ],
[ "seven", "height", "nine" ]
];
</pre>

This is especially useful when you want to display player names with colors. Example from "Hearts":
<pre>
$firstRow = [ '' ];
foreach( $players as $player_id => $player ) {
$cell = [ 'str' => '${player_name}',
'args' => [ 'player_name' => $player['player_name'] ],
'type' => 'header'
];
$firstRow[] = $cell;
}
$table[] = $firstRow;
...
</pre>

You can also use three extra attributes in the parameter array for the notification:
* '''header''': the content for this parameter displays before the table (also, the html will be parsed and player names will be colored according to the current game colors).
* '''footer''': the content for this parameter displays after the table (no parsing for coloring the player names)
* '''closing''': if this parameter is used, a button will be displayed with this label at the bottom of the popup and will allow players to close it (more easily than by clicking the top right 'cross' icon).

<pre>
$this->notifyAllPlayers( "tableWindow", '', [
"id" => 'finalScoring',
"title" => clienttranslate("Title of the scoring dialog"),
"table" => $table,
"header" => ['str' => clienttranslate('Table header with parameter ${number}'),
'args' => [ 'number' => 3 ],
],
"footer" => '<div class="myfoot"></div>',
"closing" => clienttranslate( "Closing button label" )
] );
</pre>

Note: currently id is not used - so you cannot access resulting div by id on js side
Note: any traslatable stirng have to be wrapped by clienttranslate() on top level OR it has to be recursive template.

DO NOT DO THIS:
<pre>
"footer" => '<div>'.clienttranslate( "The end" ).'</div>', // this will not work for translations!!!
</pre>

=== Scoring animated display ===

Sometimes, you may want to display a score value over an element to make the scoring easier to follow for the players (Terra Mystica final scoring for example).
You can do it with:

'''this.displayScoring(anchor_id: string, color: string, score: number | string, duration?: number, offset_x?: number, offset_y?: number): void'''

'''anchor_id''': ID of the html element to place the animated score onto (without the '#')

'''color''': hexadecimal RGB representation of the color (should be the color of the scoring player), but without a leading '#'. For instance, 'ff0000' for red.

'''score''': numeric score to display, prefixed by a '+' or '-'

'''duration''': animation duration in milliseconds (optional, default is 1000)

'''offset_x''' and '''offset_y''': if both offset_x and offset_y are defined and not null, apply the following offset (in pixels) to the scoring animation.
Note that the score is centered in the anchor, so the offsets might have to be negative if you calculate the position.

Note: if you want to display successively each score, you can use ''this.notifqueue.setSynchronous()'' function.
<pre>
setupNotifications: function() {
dojo.subscribe( 'displayScoring', this, "notif_displayScoring" );
...
}
...

notif_displayScoring: function(notif) {
const duration = notif.args.duration?notif.args.duration:1000;
this.notifqueue.setSynchronous('displayScoring', duration );
this.displayScoring( notif.args.target, notif.args.color, notif.args.score, duration);
},
</pre>

=== Speech bubble ===

For better interactivity in some games (Love Letter for example), you may use comic book style speech bubbles to express the players voices.
This is done with showBubble:

'''this.showBubble(anchor_id: string, text: string, delay?: number, duration?: number, custom_class?: string): void'''

* anchor_id - where to attach the bubble
* text - what to put in bubble, can be html
* delay - delay in milliseconds (optional, default 0)
* duration - duration of animation in milliseconds (optional, default 3000)
* custom_class - extra class to add to bubble (optional), if you need to override the default bubble style

<pre>
this.showBubble('meeple_2', _('Hello'), 0, 1000, 'pink_bubble');
</pre>

<pre>
notif_speechBubble(notif) {
var html = this.format_string_recursive(notif.args.text, notif.args.args);
this.showBubble(notif.args.target, html, notif.args.delay ?? 0, notif.args.duration ?? 1000);
},
</pre>

'''Warning''': if your bubble could overlap other active elements of the interface (buttons in particular), as it stays in place even after disappearing, you should use a custom class to give it the style "pointer-events: none;" in order to intercept click events.

Note: If you want this visually, but want to take complete control over this bubble and its animation (for example to make it permanent) you can just use div with 'discussion_bubble' class on it, and content of div is what will be shown.

== Translations ==

See [[Translations]]

== Players panels ==

=== Update players score ===

The column player_score from the player table is automatically loaded into this.scoreCtrl and therefore into the stars location on the player board. This occurs sometime after the game setup() function. However this score must be updated as the game progresses using notifications.

Note: this.scoreCtrl[player_id] is object of class [[Counter]], you can use other counter API.

Increase a player score (with a positive or negative number):

<pre>
this.scoreCtrl[ player_id ].incValue( score_delta );
</pre>

Set a player score to a specific value:

<pre>
this.scoreCtrl[ player_id ].setValue( new_score );
</pre>

Set a player score to a specific value with animation:

<pre>
this.scoreCtrl[ player_id ].toValue( new_score );
</pre>

Typical usage would be (that will process 'score' notification):
<pre>
setupNotifications : function() {
...
dojo.subscribe('score', this, "notif_score");
},
notif_score: function(notif) {
this.scoreCtrl[notif.args.player_id].setValue(notif.args.player_score);
},
</pre>

=== Adding stuff to player's panel ===

At first, create a new "JS template" string in your template (tpl) file:

(from Gomoku example)
<pre>
var jstpl_player_board = '\<div class="cp_board">\
<div id="stoneicon_p${id}" class="gmk_stoneicon gmk_stoneicon_${color}"></div><span id="stonecount_p${id}">0</span>\
</div>';
</pre>

Then, you add this piece of code in your JS file to add this template to each player panel:

<pre>
// Setting up player boards
for( var player_id in gamedatas.players )
{
var player = gamedatas.players[player_id];

// Setting up players boards if needed
var player_board_div = $('player_board_'+player_id);
dojo.place( this.format_block('jstpl_player_board', player ), player_board_div );
}
</pre>

(Note: the code above is of course from your "setup" function in your Javascript).

Very often, you have to distinguish current player and others players. In this case, you just have to create another JS template (ex: jstpl_otherplayer_board) and use it when "player_id" is different than "this.player_id".

=== Fixing Player Panel heights ===

You may find that the player panels don't automatically resize when adding something to (or removing something from) a player panel while the display is in portrait mode (i.e. the player summary panels are at the top of the screen rather than down the right side).

When this happens, call <pre>this.adaptPlayersPanels();</pre> This recalculates the layout and also adjusts the position of the actionbar for you.

=== Player's panel disabling/enabling ===

'''this.disablePlayerPanel(player_id: number): void'''

Disable given player panel (the panel background become gray).

Usually, this is used to signal that this played passes, or will be inactive during a while.

Note that the only effect of this is visual. There are no consequences on the behaviour of the panel itself.

'''this.enablePlayerPanel(player_id:number): void'''

Enable a player panel that has been disabled before.

'''this.enableAllPlayerPanels(): void'''

Enable all player panels that has been disabled before.

=== Player order ===

'''this.updatePlayerOrdering(): void'''

This function makes sure that player order in player's panel matches this.gamedatas.playerorder and its normally called by framework.
You can call it yoursel if you change this.gamedatas.playerorder from notification.
Also you can override this function to change defaults OR insert a non-player panel [[BGA_Studio_Cookbook#Inserting_non-player_panel]].

=== Counters ===
Note: there is bga component called "ebg/counter" this API is not using it, these methods
below declared right in core game. If you need animation for counters use ebg/counter

To use this API just create a counter dom element like this (class does not really matter)
<pre>
<div class="counter" id="bread"></div>
<div class="counter" id="coin"></div>
</pre>
The "bread" will the counter name.

The php code should send all "counters" data from getAllDatas() method like this

game.php
<pre>
protected function getAllDatas() {
// (the key must match counter_name)
$result['counters']=[
'bread' => [
'counter_name' => 'bread',
'counter_value' => 3
],
'coin' => [
'counter_name' => 'coin',
'counter_value' => 5
]
];
return $result;
}
</pre>

'''setCounter(counter_name: stirng, new_value: string | number): void'''

updates the global this.gamedatas.counters and value of node $(counter_name)
<pre>
notif_counter: function(notif) {
this.setCounter(notif.args.counter_name, notif.args.counter_value);
},
</pre>

'''incCounter(counter_name: string, delta: number): void'''
<pre>
notif_counter : function(notif) {
this.incCounter(notif.args.counter_name, notif.args.inc);
},
</pre>

'''updateCounters(counters: object): void'''

Useful for updating game counters in the player panel (such as resources).
'counters' arg is map of counters (the key must match counter_name)
{
'bread': {
'counter_name' : 'bread',
'counter_value' => 3
},
'coin': {
'counter_name' : 'coin',
'counter_value' => 5
}
}
All counters MUST be referenced in this.gamedatas.counters (means they should be send from php) and will be updated.
DOM objects referenced by 'counter_name' will have their innerHTML updated with 'counter_value'.

Usually you call this from notification

<pre>
notif_counter : function(notif) {
this.updateCounters(notif.args.counters);
},
</pre>

== BGA GUI components ==

BGA framework provides some useful ready-to-use components for the game interface:

[[Studio#BGA_Studio_game_components_reference]]

Note that each time you are using an additional component, you must declare it at the top of your Javascript file in the list of modules used.

Example if you are using "ebg.stock":
<pre>
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/stock" /// <=== we are using ebg.stock module
],
</pre>

== BGA Buttons ==

=== Basic Button ===

'''this.addActionButton(id: string, label: string, method: string | eventhandler, destination?: string, blinking?: boolean, color?: string): void'''

You can use this method to add an action button in the main action status bar (or other places).

Arguments:
* id: an element ID that should be unique in your HTML DOM document.
* label: the text of the button. Should be translatable (use _() function). Note: this can also be any html, such as "<div class='brick'></div>", see example below on how to make image action buttons.
* method: the name of your method that must be triggered when the player clicks on this button (can be name of the method on game class or handler).
* destination (optional): id of parent on where to add button, ONLY use in rare cases if location is not action bar. Use '''null''' as value if you need to specify other arguments.
* blinking (optional): if set to '''true''', the button is going blink to catch player's attention. Please DO NOT abuse blinking button. If you need button to blink after some time passed add class 'blinking' to the button later.
* color: could be '''blue''' (default), '''red''','''gray''' or '''none'''.

You should only use this method in your "onUpdateActionButtons" method. Usually, you use it like this:

<pre>
onUpdateActionButtons: function( stateName, args ) {
if (this.isCurrentPlayerActive()) {
switch( stateName ) {
case 'giveCards':
this.addActionButton( 'giveCards_button', _('Give selected cards'), 'onGiveCards' );
this.addActionButton( 'pass_button', _('Pass'), () => this.bgaPerformAction('actPass') );
break;
}
}
},
</pre>

In the example above, we are adding a "Give selected cards" button in the case we are on game state "giveCards". When player clicks on this button, it triggers our "onGiveCards" method.

Example using blinking red button:
<pre>
this.addActionButton( 'button_confirm', _('Confirm?'), 'onConfirm', null, true, 'red');
</pre>

If you want to call the handler with arguments, you can use arrow functions, like this:
<pre>
this.addActionButton( 'commit_button', _('Confirm'), () => this.onConfirm(this.selectedCardId), null, false, 'red');
</pre>

=== Image Button ===

You can use the same method, but add extra class to a button to disable the padding and style it, i.e.
<pre>
this.addActionButton( 'button_brick', '<div class="brick"></div>', ()=>{... on brick ...}, null, null, 'gray');
dojo.addClass('button_brick','bgaimagebutton');
</pre>

where

<pre>
.bgaimagebutton {
padding: 0px 12px;
min-height: 28px;
border: none;
}
</pre>

If you use this a lot, you can define a helper function, i.e.
<pre>
/**
* This method can be used instead of addActionButton, to add a button which is an image (i.e. resource). Can be useful when player
* need to make a choice of resources or tokens.
*/
addImageActionButton: function(id, div, handler, bcolor, tooltip) {
if (typeof bcolor == "undefined") {
bcolor = "gray";
}
// this will actually make a transparent button id color = gray
this.addActionButton(id, div, handler, null, false, bcolor);
// remove border, for images it better without
dojo.style(id, "border", "none");
// but add shadow style (box-shadow, see css)
dojo.addClass(id, "shadow bgaimagebutton");
// you can also add additional styles, such as background
if (tooltip) {
dojo.attr(id, "title", tooltip);
}
return $(id);
},
</pre>

=== Disabling Button ===

You can disable the '''bgabutton''' by adding the css class '''disabled''' in you js. The disabled button is still visible but is grey and not clickable.
For example in the '''onUpdateActionButtons''' :
<pre>
this.addActionButton('play_button_id', _('Play 1 to 3 cards'), 'playFunctionButton');
if (condition) {
dojo.addClass('play_button_id', 'disabled');
}
</pre>

=== Custom Buttons ===

You can create a custom button, but the BGA framework provides a standard button that requires only .css classes: '''bgabutton''' and '''bgabutton_${color}'''.

'''Examples:'''

<pre>
<a href="#" id="my_button_id" class="bgabutton bgabutton_blue"><span>My blue button</span></a>

<a href="#" id="my_button_id" class="bgabutton bgabutton_red bgabutton_big"><span>My big red button</span></a>
</pre>

'''Note''': To see it in action, check out ''Coloretto''.

=== Button outside of action bar ===

Use addActionButton() method with destination argument set
<pre>
this.addActionButton( 'commit_button', _('Confirm'), 'onConfirm', 'player_board', true, 'red');
</pre>

in example above the button will be place on object with id 'player_board'

== Image loading ==

See also [[Game_art:_img_directory]].

'''Be careful''': by default, ALL images of your img directory are loaded on a player's browser when he loads the game. For this reason, don't let in your img directory images that are not useful, otherwise it's going to slowdown the game load.

'''this.dontPreloadImage(image_file_name: string)'''

Using dontPreloadImage, you tell the interface to not preload a specific image in your img directory.

Example of use:
<pre>
this.dontPreloadImage( 'cards.png' );
</pre>

This is particularly useful if for example you have 2 different themes for a game. To accelerate the loading of the game, you can specify to not preload images corresponding to the other theme.

Another example of use: in "Gosu" game with Kamakor extension, you play with 5 sets of cards among 10 available. Cards images are organized by sets, and we only preload the images corresponding to the 5 current sets with '''ensureSpecificGameImageLoading( image_file_names_array )'''.
<pre>
// By default, do not preload anything
this.dontPreloadImage( 'cards.png' );
this.dontPreloadImage( 'clan1.png' );
this.dontPreloadImage( 'clan2.png' );
this.dontPreloadImage( 'clan3.png' );
this.dontPreloadImage( 'clan4.png' );
this.dontPreloadImage( 'clan5.png' );
this.dontPreloadImage( 'clan6.png' );
this.dontPreloadImage( 'clan7.png' );
this.dontPreloadImage( 'clan8.png' );
this.dontPreloadImage( 'clan9.png' );
this.dontPreloadImage( 'clan10.png' );
var to_preload = [];
for( i in this.gamedatas.clans )
{
var clan_id = this.gamedatas.clans[i];
to_preload.push( 'clan'+clan_id+'.png' );
}

this.ensureSpecificGameImageLoading( to_preload );

</pre>

'''Note:''' You don't need to specify to not preload game box images (game_box.png, game_box75.png...) since they are not preloaded by default.

'''this.ensureSpecificGameImageLoading(list: string[])'''

This is oppostive of dontPreloadImage - its ensure specific images is loaded. Note: only makes sense if preload list is empty, otherwise everything is loaded anyway

'''load specific images'''
All images that will be preloaded stored in g_img_preload. If you want to override it directly - there is no API, but you can do this in GAME constructor

g_img_preload = ['tokens.png', 'trains.png', 'loc_plan.png', 'eng.png', 'eng-back.png'];

You can also set it to empty array and call ensureSpecificGameImageLoading() on specific images

== Sounds ==

Add a custom sound and make it load with your interface:

Add this in your template (.tpl) file:
<pre>
<audio id="audiosrc_<gamename>_<yoursoundname>" src="{GAMETHEMEURL}img/<gamename>_<yoursoundname>.mp3" preload="none" autobuffer></audio>
<audio id="audiosrc_o_<gamename>_<yoursoundname>" src="{GAMETHEMEURL}img/<gamename>_<yoursoundname>.ogg" preload="none" autobuffer></audio>
</pre>

Note: this is a requirement to provide both a mp3 and a ogg file with the names <code><gamename>_<yoursoundname>[.ogg][.mp3]</code>.

Play the sound (from your .js file):

<pre>
playSound('<gamename>_<yoursoundname>'); // do not add 'this.' - its a global function
</pre>

Disable the standard "move" sound for this move (to replace it with your custom sound):

Add this to your notification handler:

<pre>
this.disableNextMoveSound();
</pre>

Note: it only disable the sound for the next move.

== Title bar and states ==

=== Client states ===

Client states is a way to simulate the state transition but without actually going
to server. It is usefull when you need to ask user multiple questions before you
send things to server

'''this.setClientState(newState: string, args: object)'''

Example:
this.setClientState("client_playerPicksLocation", {
descriptionmyturn : _("${you} must select location"),
});

For more information see [[BGA_Studio_Cookbook#Multi_Step_Interactions:_Select_Worker.2FPlace_Worker_-_Using_Client_States]]

'''this.restoreServerGameState()'''
If you are in client state it will restore the current server state (cheap undo)

'''this.on_client_state'''
Boolean indicating that we are in client state

=== Title bar ===
If you simply want to show something in title bar you can do it directly
$('pagemaintitletext').innerHTML = text;

This however will not work with parameters and will not draw You in color,
if you want to do proper args rendering use method below

;'''this.removeActionButtons()'''
Removes all buttons from title bar

;'''this.updatePageTitle()'''
:This function allows to update the current page title and turn description according to the game state arguments. If the current game state description this.gamedatas.gamestate.descriptionmyturn is modified before calling this function it allows to update the turn description without changing state. This will handle arguments substitutions properly.

Note: this functional also will calls this.onUpdateActionButtons, if you want different buttons then state defaults, use method in example to replace them, if it becomes too clumsy use client states (see above)

Example from Terra Mystica:
<pre>
onClickFavorTile: function( evt ) {
...
if ( ... ) {
this.gamedatas.gamestate.descriptionmyturn = _('Special action: ') + _('Advance 1 space on a Cult track');
this.updatePageTitle();
this.removeActionButtons();
this.addActionButton( ... );
...
return;
}
...

}
</pre>

== User preferences ==
'''this.getGameUserPreference(pref_id)'''

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

'''this.setGameUserPreference(pref_id, value)'''

Programmatically change a user preference. It will have the same effect as if the player changed the value in the select combo box, in the top-right menu.

'''this.onGameUserPreferenceChanged'''

A callback you can define if you want to be notified when a user changes a user preference.

Example:<pre>
onGameUserPreferenceChanged: function(pref_id, pref_value) {
switch (pref_id) {
case 201:
document.getElementsByTagName('html')[0].classList.toggle('dark-background', pref_value == 2);
break;
}
}
</pre>

== Other useful stuff ==

'''dojo.hitch'''

With dojo.hitch, you can create a callback function that will run with your game object context whatever happen.

Typical example: display a BGA confirmation dialog with a callback function created with dojo.hitch:

<pre>
this.confirmationDialog( _('Are you sure you want to make this?'), dojo.hitch( this, function() {
this.bgaPerformAction('makeThis');
} ) );
</pre>

In the example above, using dojo.hitch, we ensure that the "this" object will be set when the callback is called.

NOTE: In modern JS there are lambdas that eliminate need for that, the example above will look like this
<pre>
this.confirmationDialog( _('Are you sure you want to make this?'), () => this.bgaPerformAction( 'makeThis') );
</pre>

;'''onScreenWidthChange()'''
:This function can be overridden in your game to manage some resizing on the client side when the browser window is resized. This function is also triggered at load time, so it can be used to adapt to the :viewport size at the start of the game too.

; this.bRealtime
: Return true if the game is in realtime. Note that having a distinct behavior in realtime and turn-based should be exceptional.

; g_replayFrom
: Global contains replay number in live game, it is set to undefined (i.e. not set) when it is not a replay mode, so consequentially the good check is '''typeof g_replayFrom != 'undefined'''' which returns true if the game is in replay mode <i>during the game</i> (the game is ongoing but the user clicked "replay from this move" in the log)

; g_archive_mode
: Returns true if the game is in archive mode <i>after the game</i> (the game has ended)

; this.instantaneousMode
: Returns true during replay/archive mode if animations should be skipped. Only needed if you are doing custom animations. (The BGA-provided animation functions like <i>this.slideToObject()</i> automatically handle instantaneous mode.)
: Technically, when you click "replay from move #20", the system replays the game from the very beginning with moves 0 - 19 happening in instantaneous mode and moves 20+ happening in normal mode.

; g_tutorialwritten
: Returns an object like the below if the game is in tutorial mode, or undefined otherwise. Tutorial mode is a special case of archive mode where comments have been added to a previous game to teach new players the rules.
{
author: "91577332",
id: "576",
mode: "view"
status: "alpha"
version_override: null
viewer_id: "84554161"
}

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

[[Category:Studio]]

Game interface logic: Game.js

2024-09-25T17:45:29Z

Sguzzer Gunayer: /* Moving elements */

{{Studio_Framework_Navigation}}

__TOC__

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

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

== File structure ==

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

Here is the basic structure:

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

More details:

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

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

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

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

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

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

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

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

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

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

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

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

== Dojo framework ==

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

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

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

== Javascript minimization (after July 2020) ==

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

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

== Accessing Players Information ==

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

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

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

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

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

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

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

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

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

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

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

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

== Accessing and manipulating the DOM ==

=== Element by Id ===

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

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

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

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

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

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

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

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

=== Style ===

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

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

Examples:

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

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

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

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

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

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

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

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

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

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

=== Classes ===

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

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

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

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

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

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

Example from ''Reversi'':

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

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

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

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

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

'''Vanilla JS classList'''

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

=== Attributes ===

;dojo.attr

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

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

'''Vanilla JS attr'''

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

=== Queries ===

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

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

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

// Count number of tokens (i.e., elements of class "token") on the board (i.e., the element with id "board"):
dojo.query( '#board .token' ).length;
</pre>

But what is really cool with dojo.query is that you can combine it with almost all methods above.

Examples:
<pre>
// Trigger a method when the mouse enter in any element with class "meeple":
dojo.query( '.meeple' ).connect( 'onmouseenter', this, 'myMethodToTrigger' );

// Hide all meeples who are on the board
dojo.query( '#board .meeple' ).style( 'display', 'none' );
</pre>

'''Vanilla JS query'''

var cards=document.querySelectorAll(".hand .card");// all cards in all hands
var cards=$('hand').querySelectorAll(".card");// all cards in specific hand
var card=document.querySelector(".hand .card");// first card or null if none (super handy)

=== Creating and Destroying elements ===

'''dojo.empty(node: ElementOrId)'''

Remove all children of the node element
dojo.empty('my_hand');

'''dojo.destroy(node: ElementOrId)'''

Remove the element
dojo.destroy('my_token');

dojo.query(".green", mynode).forEach(dojo.destroy); // this remove all subnode of class green from mynode

'''dojo.create(tag: string, attributes?: obj, parent?: ElementOrId): Element'''

Create element

dojo.create("div", { class: "yellow_arrow" }, parent); // this creates div with class yellow_array and places it in "parent"

'''this.format_block(name: string, args: object): string'''

This bga function that takes global var from template file and substitute variables, typical use would be

var player = gamedatas.players[player_id];
var div = this.format_block('jstpl_player_board', player ); // var jstpl_player_board = ... is defined in .tpl file
Note: result is trimmed

'''this.format_string(name: string, args: object): string'''

This bga function just substitute variables in a string, i.e.
<pre>
var div = this.format_string('<div color="${player_color}"></div>', {player_color: '#ff0000'} );
</pre>
Note: result is trimmed

Note: this can be replaced by using backquoted string now:
const player_color = '#ff0000';

const div = ``;
'''this.format_string_recursive'''

This bga function is similar to this.format_string but is capable of processing recursive argument structures and translations. It is used to format server notifications.

TODO: find better place for these function docs

=== Moving elements ===

'''dojo.place(node: string | Element, refNode: ElementOrId, pos?: string | number): Element'''

dojo.place is the best function to insert HTML code somewhere in your game interface without breaking something. It is much better to use than the '''innerHTML=''' method if you must insert HTML tags and not only values.

node: can be a string or a DOM node. If it is a string starting with “<”, it is assumed to be an HTML fragment, which will be created. Otherwise it is assumed to be an id of a DOM node.

<pre>
// Insert your HTML code as a child of a container element
dojo.place( "<div class='foo'></div>", "your_container_element_id" );
</pre>

pos: optional argument. Can be a number or one of the following strings: “before”, “after”, “replace”, “only”, “first”, or “last”. If omitted, “last” is assumed.

* "replace": replace the container element with my_node element
* "first": places the node as a child of the reference node. The node is placed as the first child.
* "last" (default): places the node as a child of the reference node. The node is placed as the last child.
* "before": places the node right before the reference node.
* "after": places the node right after the reference node.
* "only": replaces all children of the reference node with the node.

this parameter can be a positive integer. In this case, the node will be placed as a child of the reference node with this number (counting from 0). If the number is more than number of children, the node will be appended to the reference node making it the last child.

<pre>
// Replace all children of container with my_node
dojo.place( $('my_node'), "your_container_element_id", "only" );
</pre>

See also full doc on dojo.place: [https://dojotoolkit.org/reference-guide/1.7/dojo/place.html]

Usually, when you want to insert some piece of HTML in your game interface, you should use "[[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl#Javascript_templates|Javascript templates]]".

But you can also relocate elements like that. Note: it won't animate if you do that.

'''this.placeOnObject(mobile_obj: ElementOrId, target_obj: ElementOrId): void'''

places mobile_obj on target_obj, set the absolute positions and centers the mobile_obj on target_obj,
effect is immediate

This is not really an animation, but placeOnObject is frequently used before starting an animation.

Example:
<pre>
// (We just created an object "my_new_token")

// Place the new token on current player board
this.placeOnObject( "my_new_token", "overall_player_board_"+this.player_id );

// Then slide it to its position on the board
this.slideToObject( "my_new_token", "a_place_on_board" ).play();
</pre>

'''this.placeOnObjectPos(mobile_obj: ElementOrId, target_obj: ElementOrId, target_x: number, target_y: number): void'''

This method works exactly like placeOnObject, except than you can specify some (x,y) coordinates (in px). This way, the center of "mobile_obj" will be placed to the specified x,y position relatively to the center of "target_obj".

''Note: the placement works differently from this.slideToObjectPos'', since coordinates are calculated based on the center of objects.

'''this.attachToNewParent(mobile_obj: ElementOrId, target_obj: ElementOrId): void'''

With this method, you change the HTML parent of "mobile_obj" element without moving it.
"target_obj" is the new parent of this element. The beauty of
attachToNewParent is that the mobile_obj element DOES NOT MOVE during this process.

What happens is that the method calculate a relative position of mobile_obj to make sure it does not move after the HTML parent changes.

Why using this method?

Changing the HTML parent of an element can be useful for the following reasons:
* When the HTML parent moves, all its child are moving with them. If some game elements is no more linked with a parent HTML object, you may want to attach it to another place.
* The z_order (vertical order of display) depends on the position in the DOM, so you may need to change the parent of some game elements when they are moving in your game area.

'''CAREFUL''': this function destroys original object and places a clone onto a new parent, this will break all references to this HTML element (ex: dojo.connect).
If you need version that does not destroy the object but the same otherwise see [[BGA_Studio_Cookbook#Attach_to_new_parent_without_destroying_the_object]]

== Animations ==

===Dojo Animations===

BGA animations is based on Dojo Animation ([http://dojotoolkit.org/documentation/tutorials/1.8/animation/ see tutorial here]).

However, most of the time, you can just use methods below, which are built on top of Dojo Animation.

Note: one interesting method from Dojo that could be useful from time to time is "Dojo.Animation". It allows you to make any CSS property "slide" from one value to another.

Note 2: the slideTo methods are not compatible with CSS transform (scale, zoom, rotate...). If possible, avoid using CSS transform on nodes that are being slided. Eventually, the only possible solution to make these 2 compatible is to disable all CSS transform properties, use slideToObjectPos/placeOnObjectPos, and then apply them again.

===Sliding===

'''this.slideToObject(mobile_obj: ElementOrId, target_obj: ElementOrId, duration?: number, delay?: number): Animation'''

You can use slideToObject to "slide" an element to a target position.

Sliding element on the game area is the recommended and the most used way to animate your game interface. Using slides allow players to figure out what is happening on the game, as if they were playing with the real boardgame.

The parameters are:
* mobile_obj: the ID of the object to move. This object must be "relative" or "absolute" positioned.
* target_obj: the ID of the target object. This object must be "relative" or "absolute" positioned. Note that it is not mandatory that mobile_obj and target_obj have the same size. If their size are different, the system slides the center of mobile_obj to the center of target_obj.
* duration: (optional) defines the duration in millisecond of the slide. The default is 500 milliseconds.
* delay: (optional). If you defines a delay, the slide will start only after this delay. This is particularly useful when you want to slide several object from the same position to the same position: you can give a 0ms delay to the first object, a 100ms delay to the second one, a 200ms delay to the third one, ... this way they won't be superposed during the slide.

BE CAREFUL: The method returns an dojo.fx animation, so you can combine it with other animation if you want to. It means that you have to call the "play()" method, otherwise the animation WON'T START.

Example:
<pre>
this.slideToObject( "some_token", "some_place_on_board" ).play();
</pre>

'''this.slideToObjectPos(mobile_obj: ElementOrId, target_obj: ElementOrId, target_x: number, target_y: number, duration?: number, delay?: number): Animation'''

This method does exactly the same as "slideToObject", except than you can specify some (x,y) coordinates. This way, "mobile_obj" will slide to the specified x,y position relatively to "target_obj".

Example: slide a token to some place on the board, 10 pixels from the top:
<pre>
this.slideToObjectPos( "some_token", "some_place_on_board", 0, 10 ).play();
</pre>

'''this.slideTemporaryObject(mobile_obj_html: string, parent: ElementOrId, from: ElementOrId, to: ElementOrId, duration?: number, delay?: number): Animation'''

This method is useful when you want to slide a temporary HTML object from one place to another. As this object does not exists before the animation and won't remain after, it could be complex to create this object (with dojo.place), to place it at its origin (with placeOnObject) to slide it (with slideToObject) and to make it disappear at the end.

slideTemporaryObject does all of this for you:
* mobile_obj_html is a piece of HTML code that represent the object to slide.
* parent is the ID of an HTML element of your interface that will be the parent of this temporary HTML object.
* from is the ID of the origin of the slide.
* to is the ID of the target of the slide.
* duration/delay works exactly like in "slideToObject"

Example:
<pre>
this.slideTemporaryObject( '<div class="token_icon"></div>', 'tokens', 'my_origin_div', 'my_target_div' ).play();
</pre>

===Destroy===
'''this.slideToObjectAndDestroy(mobile_obj: ElementOrId, target_obj: ElementOrId, duration?: number, delay?: number): void'''

This method is a handy shortcut to slide an existing HTML object to some place then destroy it upon arrival. It can be used for example to move a victory token or a card from the board to the player panel to show that the player earns it, then destroy it when we don't need to keep it visible on the player panel.

It works the same as this.slideToObject and takes the same arguments, but it starts the animation.

CAREFUL: Make sure nothing is creating the same object at the same time the animation is running, because this will cause some random disappearing effects

Example:
<pre>
this.slideToObjectAndDestroy( "some_token", "some_place_on_board", 1000, 0 );
</pre>

'''this.fadeOutAndDestroy( node: string | Element, duration?: number, delay?: number):''' '''void'''

This function fade out the target node, then destroy it. Its starts the animation.
* duration/delay works exactly like in "slideToObject"

Example:
<pre>
this.fadeOutAndDestroy( "a_card_that_must_disappear" );
</pre>

CAREFUL: the HTML node still exists until during few milliseconds, until the fadeOut has been completed.
Make sure nothing is creating same object at the same time as animation is running, because you will be some random dissapearing effects

===Rotating elements===

This example combines "Dojo.Animation" method and a CSS property transform that allow you to rotate the element.
<pre>
// node is Element we rotating
var animation = new dojo.Animation({
curve: [fromDegree, toDegree],
onAnimate: (v) => {
node.style.transform = 'rotate(' + v + 'deg)';
}
});

animation.play();
</pre>

BGA has its own interface to rotate

'''this.rotateTo(node: string | Element, degree: number): void'''

It starts the animation, and stored the rotation degree in the class, so next time you rotate object - it is additive.
There is no animation hooks in this one, if you need to change any parameters use dojo animation above.

There is also '''rotateInstantTo''' with same signature which does not animate

===Animation Callbacks===

If you wish to run some code only after an animation has completed you can do this by linking a callback method to 'onEnd'.

<pre>
var animation_id = this.slideToObject( mobile_obj, target_obj, 500 );
dojo.connect(animation_id, 'onEnd', () => {
// do something here
});
animation_id.play();
</pre>

If you wish to call a second animation after the first (rather than general code) then you can use a dojo animation chain (see tutorial referenced above).

== Players input ==

=== Connecting ===
'''dojo.connect(element: Element, event: string, context: object, method: eventHandler): any'''

'''dojo.connect(element: Element, event: string, hander: eventHandler): any'''

Used to associate a player event with one of your notification methods.

Example: associate a click on an element ("my_element") with one of our methods ("onClickOnMyElement"):
<pre>
dojo.connect( $('my_element'), 'onclick', this, 'onClickOnMyElement' );
</pre>

Same idea but base on query (i.e. all element of 'pet' class)
dojo.query(".pet").connect('onclick', this, 'onPet');

Note: if you need to disconnect the handler you have to store handler returned from this method, i.e.

<pre>
var handler = dojo.connect(...);
...
dojo.disconnect(handler);
</pre>

If you don't store the handler - you have to destroy the object to disconnect it

Typical function that implements the input handler will look like this

<pre>
onPet: function(event) {
var id = event.currentTarget.id;
console.log('onPet ' + id);
dojo.stopEvent(event);
if (this.gamedatas.gamestate.name == 'playerTurnPet') {
this.bgaPerformAction('actPlayPet', {card: id});
} else {
this.showMoveUnauthorized();
}
}
</pre>

'''this.connect(element: ElementOrId, event: string, method: eventHandler): void'''

Used to associate a player event with one of your notification methods.

this.connect( $('my_element'), 'onclick', 'onClickOnMyElement' );

Or you can use an in-place handler

this.connect( $('my_element'), 'onclick', (e) => { console.log('boo'); } );

Note that this function stores the connection handler. That is the only real difference between '''this.connect''' and '''dojo.connect'''. If you plan to destroy the element you connected, you '''must''' call this.disconnect() to prevent memory leaks.
This function is mainly for permanent objects - if you just want to connect the temp object you should probably not use this method but use dojo.connect which won't require any clean-up.

'''this.connectClass(cssClassName: string, event: string, method: eventHandler): void'''

Same as connect(), but for all the nodes set with the specified cssClassName.

this.connectClass('pet', 'onclick', 'onPet');

'''this.disconnect(element: ElementOrId, event: string): void'''

Disconnect event handler (previously registered with this.connect or this.connectClass).

this.disconnect( $('my_element'), 'onclick');

Note: dynamic connect/disconnect is for advanced cases ONLY, you should always connect elements statically if possible, i.e. in setup() method.

'''this.disconnectAll(): void'''

Disconnect all previously registed event handlers (registered via this.connect or this.connectClass)

this.disconnectAll();

=== Actions ===

'''this.bgaPerformAction(action: string, args?: object, options: object = { lock: true, checkAction: true }): Promise<void>'''

Triggers an action on the backend. This is a combination of checkAction and ajaxcall, returning a Promise which resoves when ajaxcall ends.

This method must be used to send a player input to the game server. '''It should not be triggered programmatically''', especially not in loops, in callbacks, in notifications, or in onEnteringState/onUpdateActionButtons/onLeavingState, in order not to create race conditions or break replay game and tutorial features. It should be used only in reaction to a user action in the interface.

* action: name of the action, as it is written in "possibleactions" of the current state.
* args: an object containing the call parameters to send to the action
* options: options to tweak the call with some defaults. Default is <code>{ lock: true, checkAction: true }</code>.

Example of a standard call without args:
this.bgaPerformAction('pass');

Example of a standard call with action args:
this.bgaPerformAction('actPlayCard', { id: this.selectedCardId });

Example of a call without checking action (because player is inactive in a multiactive state):

this.bgaPerformAction('actChangeMind', {}, { checkAction: false });

Example of a call without lock (because of a special action not directly related to the game flow):

this.bgaPerformAction('actSetAutoBid', { alwaysBidUntil: 500 }, { lock: false, checkAction: false });

Example of call with reaction to exception:
this.bgaPerformAction('actPlayCard', { id: this.selectedCardId }).catch(()=>{ this.selectedCardId = undefined; });

Example of call with reaction to success:
this.bgaPerformAction('actPlayCard', { id: this.selectedCardId }).then(()=>{ this.unselectAll(); });

'''this.ajaxcall(url, parameters, obj_callback, callback, callback_anycase?, ajax_method?: string)'''

''Note: bgaPerformAction is a simpler way to use ajax calls, ajaxcall stays in the doc for legacy reasons only and should not be used in new projects.''

Same warning as '''this.bgaPerformAction''' about using on user action only.

* url: the url of the action to perform. For a game, it must be: "/<mygame>/<mygame>/myAction.html"
* parameters: an array of parameter to send to the game server.
** Note that "lock: true" must always be specified in this list of parameters in order the interface can be locked during the server call. Cannot use lock: false - to not lock it has to be undefined.
** Note: Restricted parameter names (please don't use them):
*** "action"
*** "module"
*** "class"
* obj_callback: must be set to "this".
* callback (non-optional but rarely used): a function to trigger when the server returns result and everything went fine (not used, as all data handling is done via notifications).
* callback_anycase: (optional) a function to trigger when the server returns ok OR error. If no error this function is called with parameter value false. If an error occurred, the first parameter will be set to true, the second will contain the error message sent by the PHP back-end, and the third will contain an error code.
* ajax_method: (optional and rarely used) if you need to send large amounts of data (over 2048 bytes), you can set this parameter to 'post' (all lower-case) to send a POST request as opposed to the default GET. This works, but was not officially documented, so only use if you really need to.

Usage:
<pre>
this.ajaxcall( '/mygame/mygame/actMyAction.html', { lock: true,
arg1: myarg1,
arg2: myarg2
}, this, (result)=>{} );
</pre>

'''this.checkAction(action: string, nomessage?: boolean): boolean '''

Check if player can do the specified action by taking into account:
* if interface is locked it will return false and show message "An action is already in progress", unless nomessage set to true
* if player is not active it will return false and show message "This is not your turn", unless nomessage set to true
* if action is not in list in possible actions (defined by "possibleaction" in current game state) it will return false and show "This move is not authorized now" error (unconditionally).
* otherwise returns true
Example:
<pre>
function onClickOnGameElement( evt ) {
if( this.checkAction( "actMyAction" ) ) {
// Do the action
}
}
</pre>

'''this.checkPossibleActions(action: string): boolean'''

* this is independent of the player being active, so can be used instead of this.checkAction(). This is particularly useful for multiplayer states when the player is not active in a 'player may like to change their mind' scenario. Unlike this.checkAction, this function does NOT take interface locking into account

* if action is not in list in possible actions (defined by "possibleaction" in current game state) it will return false and show "This move is not authorized now" error (unconditionally).
* otherwise returns true

function onChangeMyMind( evt ) {
if( this.checkPossibleActions( "actMyAction" ) ) {
// Do the action
}
}

'''this.checkLock(nomessage?: boolean): boolean'''

When using "lock: true" in ajax call you can use this function to check if interface is in lock state (it will be locked during server call and notification processing).
This check can be used to block some other interactions which do not result in ajaxcall or if you want to suppress errors. Note: normally you only need to use this.checkAction(...), this is for advanced cases.

It will also show error unless nomessage is set to true

function onChangeMyMind( evt ) {
if( this.checkLock() ) {
// Do the action
}
}

== Notifications ==

When something happens on the server side, your game interface Javascript logic received a notification.
If you have not done so yet check what notification are in [[Main_game_logic:_yourgamename.game.php#Notifications]]

Here's how you can handle these notifications on the client side.

=== Subscribe to notifications ===

'''dojo.subscribe(notif_type: string, callback_obj: Object, handler: string|handler)'''
* notif_type - notification type/name send by php server
* callback_obj - usually this
* handler - if string method of callback_obj with name name is called, when notification is called, with notification object as parameter (see below)

Your Javascript "setupNotifications" method is the place where you can subscribe to notifications from your PHP code.

Here's how you associate one of your Javascript method to a notification "playDisc" (from Reversi example):

<pre>
setupNotifications: function() {
...
dojo.subscribe('playDisc', this, "notif_playDisc");
},
</pre>

Note: the "playDisc" corresponds to the name of the notification you define it in your PHP code, in your "notifyAllPlayers" or "notifyPlayer" method.

Then, you have to define your "notif_playDisc" method:

<pre>
notif_playDisc: function(notif) {
// Remove current possible moves (makes the board more clear)
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );
this.addDiscOnBoard( notif.args.x, notif.args.y, notif.args.player_id );
},
</pre>

In a notification handler like our "notif_playDisc" method, you can access all notifications arguments with "notif.args".

Example:

PHP

<pre>
$this->notifyAllPlayers( "apples", clienttranslate('player takes ${count} apples'), [ "count" => 3 ] );
</pre>

JavaScript

<pre>
setupNotifications: function() {
dojo.subscribe( 'apples', this, 'notif_apples' );
},

notif_apples: function(notif) {
//You can access the "count" like this:
alert("count = " + notif.args.count);
}
</pre>

=== The notification Object received by client ===

When sending a notification on your PHP, the client side will receive an Object with the following attributes:

* type - type of the notification (as passed by php function)
* log - the log string passed from php notification
* args - This is the arguments that you passed on your notification method on php
* bIsTableMsg - is true when you use [[Main_game_logic:_yourgamename.game.php#NotifyAllPlayers|NotifyAllPlayers]] method (false otherwise)
* channelorig - information about table ID (formatted as : "/table/t[TABLE_NUMBER]")
* gamenameorig - name of the game
* move_id - ID of the move associated with the notification
* table_id - ID of the table (comes as string)
* time - UNIX GMT timestamp
* uid - unique identifier of the notification
* h - unknown

'' Note that those information were inferred from observation on console log. If an Admin can confirm/correct (and remove this line), you're welcome :)''

=== Ignoring notifications ===

Sometimes you need to ignore some notification on client side. You don't want them to be shown in game log and you don't want them to be handled.

The most common use case is when a player gets private information. They will receive a specific notification (such as "You received Ace of Heart"), while other players would receive more generic notification ("Player received a card").

In X.game.php
<pre>
$this->notifyAllPlayers("dealCard", clienttranslate('${player_name} received a card'), [
'player_id' => $playerId,
'player_name' => $this->getActivePlayerName()
]);

$this->notifyPlayer($playerId, "dealCardPrivate", clienttranslate('You received ${cardName}'), [
"type" => $card["type"],
"cardName" => $this->getCardName($card["type"])
]);
</pre>

The problem with this approach is that the active player will receive two notifications:
* Player1 received a card
* You received Ace of Hearts

Hence, notification ignoring.

NOTE: You can think that it would be possible to send such notification to all players except active just by using notifyPlayer and it seems to work. The problem however is that table spectators would miss such notification and their user interface (and game log) wouldn't be updated. Since there is no way to send notification just to spectators, ignoring the notification (or "filtering") is the only reasonable solution.

'''setIgnoreNotificationCheck(notif_type: string, predicate: ((notif: Notif)=>boolean))'''
This method will set a check whether any of notifications of specific type should be ignored.

The parameters are:
* notif_type: type of the notification
* predicate (notif => boolean): a function that will receive notif object and will return true if this specific notification should be ignored

Before dispatching any notification of this type, the framework will call predicate to check whether notification should be ignored, if it return true - the notification will be dispatched, i.e. logged or handled.

<pre>
this.notifqueue.setIgnoreNotificationCheck( 'dealCard', (notif) => (notif.args.player_id == this.player_id) );
</pre>

IMPORTANT: Remember that this notification is ignored on the client side, but was still received by the client. Therefore it shouldn't contain any private information as cheaters can get it. In other words this is not a way to hide information.

IMPORTANT: When a game is reloaded with F5 or when opening a turn based game, old notifications are replayed as history notification. They are used just to update the game log and are stripped of all arguments except player_id, i18n and any argument present in message. If you use and other argument in your predicate you should '''preserve''' it as explained [[Main_game_logic:_yourgamename.game.php#Notify_players|here]].

=== Synchronous notifications ===

When several notifications are received by your game interface, these notifications are processed immediately, one after the other, in the same exact order they have been generated in your PHP game logic.

However, sometimes, you need to give some time to the players to figure out what happened on the game before jumping to the next notification. Indeed, in many games, there are a lot of automatic actions, and the computer is going to resolve all these actions very fast if you don't tell it not to do so.

As an example, for Reversi, when someone is playing a disc, we want to wait 500 milliseconds before doing anything else in order the opponent player can figure out what move has been played.

Here's how we do this, right after our subscription:
<pre>
dojo.subscribe( 'playDisc', this, "notif_playDisc" );
this.notifqueue.setSynchronous( 'playDisc', 500 ); // Wait 500 milliseconds after executing the playDisc handler
</pre>

-----

It is also possible to control the delay timing dynamically (e.g., using notification args). As an example, maybe your notification 'cardPlayed' should pause for a different amount of time depending on the number or type of cards played.

For this case, use '''setSynchronous''' without specifying the duration and use '''setSynchronousDuration''' within the notification callback.

* NOTE: If you forget to invoke '''setSynchronousDuration''', the game will remain paused forever!

<pre>
setupNotifications: function () {
dojo.subscribe( 'cardPlayed', this, 'notif_cardPlayed' );
this.notifqueue.setSynchronous( 'cardPlayed' ); // wait time is dynamic
...
},

notif_cardPlayed: function (notif) {
// MUST call setSynchronousDuration

// Example 1: From notification args (PHP)
this.notifqueue.setSynchronousDuration(notif.args.duration);
...

// Or, example 2: Match the duration to a Dojo animation
var anim = dojo.fx.combine([
...
]);
anim.play();
this.notifqueue.setSynchronousDuration(anim.duration);
},
</pre>

You can also manually call this.notifqueue.setSynchronousDuration(0) once client operations are finished, but be careful that even fast replay still has a path to call it.

'''WARNING: combining synchronous and ignored notifications'''
You must be careful when combining dynamic synchronous durations (as described above) with ignored notifications. If you have a conditionally ignored notification like this (see below section):

<pre>this.notifqueue.setIgnoreNotificationCheck( 'myNotif', (notif) => (notif.args.player_id == this.player_id) /* or any other condition */ )</pre>

then you CANNOT do

<pre>this.notifqueue.setSynchronous('myNotif');</pre>

as, when the ignored check passes, the notification handler, in which `this.notifqueue.setSychronousDuration` is called, is never called and so the duration is never set and interface locking results.

The workaround is to set a "dummy" time:

<pre>this.notifqueue.setSynchronous('myNotif', 5000);</pre>

whose value is irrelevant but must be large enough to cover the time before the notification handler is called. The large value never actually comes into play because the notification is either ignored, or the synchronous duration is reset to a sensible value inside the handler.

=== Pre-defined notification types ===

'''tableWindow''' - This defines notification to display [[Game_interface_logic:_yourgamename.js#Scoring_dialogs|Scoring Dialogs]], see below.

'''message''' - This defines notification that shows on players log and have no other effect (technically any unhandled notification will do the same but its recommended to use this keyword for consistency)

// You can call this on php side without doing anything on client side
self::notifyAllPlayers( 'message', clienttranslate('hello'), [] );

'''simplePause''' - This notification will just delay other notifications, maybe useful if you know you need some extra time for animation or something. Requires a time parameter.

<pre>
self::notifyAllPlayers( 'simplePause', '', [ 'time' => 500] ); // time is in milliseconds
</pre>

Note: the following types are RESERVED by framework, do not use:

gameStateChange gameStateChangePrivateArg gameStateMultipleActiveUpdate newActivePlayer playerstatus yourturnack clockalert tableInfosChanged playerEliminated tableDecision archivewaitingdelay end_archivewaitingdelay replaywaitingdelay end_replaywaitingdelay replayinitialwaitingdelay end_replayinitialwaitingdelay aiPlayerWaitingDelay replay_has_ended updateSpectatorList wouldlikethink updateReflexionTime undoRestorePoint resetInterfaceWithAllDatas zombieModeFail zombieModeFailWarning aiError skipTurnOfPlayer zombieBack allPlayersAreZombie gameResultNeutralized playerConcedeGame showTutorial showCursor showCursorClick skipTurnOfPlayerWarning banFromTable resultsAvailable switchToTurnbased newPrivateState infomsg

== Tooltips ==

=== Adding static tooltips ===

'''this.addTooltip(nodeId: string, helpStringTranslated: string, actionStringTranslated: string, delay?: number): void'''

Add a simple text tooltip to the DOM node.

Specify 'helpStringTranslated' to display some information about "what is this game element?".
Specify 'actionStringTranslated' to display some information about "what happens when I click on this element?".

You must specify both of the strings. You can only use one and specify an empty string ('') for the other one.

When you pass text directly function _() must be used for the text to be marked for translation! Except for empty string.

Parameter "delay" is optional. It is primarily used to specify a zero delay for some game element when the tooltip gives really important information for the game - but remember: no essential information must be placed in tooltips as they won't be displayed in some browsers (see [[BGA_Studio_Guidelines|Guidelines]]).

Example:
<pre>
this.addTooltip( 'cardcount', _('Number of cards in hand'), '' );
</pre>

Note: this generates static tooltip and attaches to existing dom element, if you need to generate tooltip more dynamically you have to call that method every time information about object is updated or use completely different tehnique, see dynamic tooltips below.

'''this.addTooltipHtml(nodeId: string, html: string, delay?: number): void'''

Add an HTML tooltip to the DOM node (for more elaborate content such as presenting a bigger version of a card).

'''this.addTooltipToClass(cssClass: string, helpStringTranslated: string, actionStringTranslated: string, delay?: number ): void'''

Add a simple text tooltip to all the DOM nodes set with this cssClass. See more details above for this.addTooltip.
this.addTooltipToClass( 'meeple', _('This is A Meeple'), _('Click to tickle') );

IMPORTANT: all concerned nodes must exist and have IDs to get tooltips.

'''this.addTooltipHtmlToClass(cssClass: string, html: string, delay?: number): void'''

Add an HTML tooltip to to all the DOM nodes set with this cssClass (for more elaborate content such as presenting a bigger version of a card).

IMPORTANT: all concerned nodes must exist and have IDs to get tooltips.

=== Removing static tooltips ===

'''this.removeTooltip(nodeId: string): void'''

Remove a tooltip from the DOM node with given id.

=== Advanced tooltips ===

'''force tooltip to open'''

If you want to force tooltip to open in reaction to some other action, i.e. click you can do this

this.tooltips[id].open(id)

where id is the id of the tooltip node where tooltip was installed.

'''dynamic tooltips'''

See [[BGA_Studio_Cookbook#Dynamic_tooltips]]

'''tooltips on mobile'''

Tooltips is very unreliable on mobile, it is recommended to implement some other method to obtaining same information,
such as simple click handler in dedicated "Help" mode or provide dedicated clickable areas such as corner of card.

== Warning messages ==

Sometimes, there is something important that is happening in the game and you have to make sure all players get the message. Most of the time, the evolution of the game situation or the game log is enough, but sometimes you need something more visible.

Ex: someone fulfills one of the end of the game conditions, so this is the last turn.

'''this.showMessage(msg: string, type: string): void'''

showMessage shows a message in a big rectangular area on the top of the screen of the current player, and it dissapears after few seconds (also it will be in the log in some cases).

* "msg" is the string to display. It should be translated.
* "type" can be set to "info", "error", "only_to_log" or custom string. If set to "info", the message will be an informative message on a white background. If set to "error", the message will be an error message on a red background and it will be added to log. If set to "only_to_log", the message will be added to the game log but will not popup at the top of the screen.
If set to custom string, it will be transparent, to use custom type define "head_xxx" in css, where xxx is the type. For example if you want yellow warning, use "warning" as type and add this to css:
.head_warning {
background-color: #e6c66e;
}

Important: the normal way to inform players about the progression of the game is the game log. The "showMessage" is intrusive and should not be used often.

<pre>
notif_messageinfo: function(notif) {
if (!g_archive_mode) {
var message = this.format_string_recursive(notif.log, notif.args);
this.showMessage(_('Announcement:') + " " + message, 'info');
}
},
</pre>

Show message could be used on the client side to prevent user wrong moves before it is send to server.
Example from 'battleship':
<pre>
onGrid: function(event) {
if (checkIfPlayerTriesToFireOnThemselves(event)) {
this.showMessage(_('This is your own board silly!'), 'error');
return;
}
...
},
</pre>

'''this.showMoveUnauthorized(): void'''

Shows predefined user error that move is unauthorized now

<pre>
onPet: function(event) {
if (checkPet(event)==false) {
this.showMoveUnauthorized();
return;
}
...
},
</pre>

== Dialogs ==

=== Confirmation dialog ===

When an important action with a lot of consequences is triggered by the player, you may want to propose a confirmation dialog.

CAREFUL: the general guideline of BGA is to AVOID the use of confirmation dialogs. Confirmation dialogs slow down the game and bother players. The players know that they have to pay attention to each move when they are playing online.

The situations where you should use a confirmation dialog are the following:
* It must not happen very often during a game.
* It must be linked to an action that can really "kill a game" if the player does not pay attention.
* It must be something that can be done by mistake (ex: a link on the action status bar).

'''this.confirmationDialog(message: string, yesHandler: (param: any) => void, noHandler?: (param: any) => void, param?: any): void'''

* message - message will be shown to user, use _() to translate
* yesHandler - non-optional handler to be called on yes
* noHandler - optional handler to called on no
* param - if specified, it will be passed to both handlers
NOTE: this is async function, it does not return anything and you should not do anything after, you must do everything in handlers

How to display a confirmation dialog:
<pre>
this.confirmationDialog(_("Are you sure you want to bake a pie?"), () => {
this.bakeThePie();
});
return; // nothing should be called or done after calling this, all action must be done in the handler
</pre>
With param and both handlers
<pre>
this.confirmationDialog(_("Are you sure you want to bake a pie?"),
(ingredient) => this.bakeThePie(ingredient),
(ingredient) => console.log(`cancelled baking of ${ingredient}`),
'apple');
</pre>

=== Multiple choice dialog ===

You can use this dialog to give user a choice with small amount of options

'''this.multipleChoiceDialog(message: string, choices: string[], callback: (choice: number) => void): void'''
* message - message will be shown to user, use _() to translate
* choices - array of choices
* callback - non-optional handler to be called on choice made, the choice parameter is the INDEX of the choice from the array of choices

NOTE: this is async function, it does not return anything and you should not do anything after, you must do everything in handlers
NOTE: there is no cancel handler, so make sure you gave user a choice to get out of it

Example:
<pre>
const keys = ["0", "1", "5", "10"];
this.multipleChoiceDialog(_("How many bugs to fix?"), keys, (choice) => {
if (choice==0) return; // cancel operation, do not call server action
var bugchoice = keys[choice]; // choice will be 0,1,2,3 here
this.bgaPerformAction("fixBugs", { number: bugchoice });
});
return; // must return here
</pre>

=== Generic Dialogs ===

As a general rule, you shouldn't use dialogs windows.

BGA guidelines specify that all game elements should be displayed on the main screen. Players can eventually scroll down to see game elements they don't need to see anytime, and you may eventually create anchors to move between game area section. Of course dialogs windows are very practical, but the thing is: all players know how to scroll down, and not all players know how to show up your dialog window. In addition, when the dialog shows up, players can't access the other game components.

Sometimes although, you need to display a dialog window. Here is how you do this:

// Create the new dialog over the play zone. You should store the handler in a member variable to access it later
this.myDlg = new ebg.popindialog();
this.myDlg.create( 'myDialogUniqueId' );
this.myDlg.setTitle( _("my dialog title to translate") );
this.myDlg.setMaxWidth( 500 ); // Optional

// Create the HTML of my dialog.
// The best practice here is to use [[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl#Javascript_templates|Javascript templates]]
var html = this.format_block( 'jstpl_myDialogTemplate', {
arg1: myArg1,
arg2: myArg2,
...
} );

// Show the dialog
this.myDlg.setContent( html ); // Must be set before calling show() so that the size of the content is defined before positioning the dialog
this.myDlg.show();

// Now that the dialog has been displayed, you can connect your method to some dialog elements
// Example, if you have an "OK" button in the HTML of your dialog:
dojo.connect($('my_ok_button'), 'onclick', this, (event) => {
event.preventDefault();
this.myDlg.destroy();
});

If necessary, you can remove the default top right corner 'close' icon, or replace the function called when it is clicked:
// Removes the default close icon
this.myDlg.hideCloseIcon();

// Replace the function call when it's clicked
this.myDlg.replaceCloseCallback((event) => { ... });

=== Scoring dialogs ===

Sometimes at the end of a round you want to display a big table that details the points wins in each section of the game.

Example: in Hearts game, we display at the end of each round the number of "heart" cards collected by each player, the player who collected the Queen of Spades, and the total number of points loose by each player.

Scoring dialogs are managed entirely on '''PHP side''', but they are described here as their effects are visible only on client side.

Displaying a scoring dialog is quite simple and is using a special notification type: "tableWindow":
<pre>
// on PHP side:
$this->notifyAllPlayers( "tableWindow", '', array(
"id" => 'finalScoring',
"title" => clienttranslate("Title of the scoring dialog"),
"table" => $table
));
</pre>

The "table" argument is a 2 dimensional PHP array that describes the table you want to display, line by line and column by column.

Example: display an 3x3 array of strings
<pre>
$table = [
[ "one", "two", "three" ], // This is my first line
[ "four", "five", "six" ], // This is my second line
[ "seven", "height", "nine" ] // This is my third line
];
</pre>

As you can see above, in each "cell" of your array you can display a simple string value. But you can also display a complex value with a template and associated arguments like this:
<pre>
$table = [
[ "one", "two", [ "str" => clienttranslate("a string with an ${argument}"), "args" => [ 'argument' => 'argument_value' ] ] ],
[ "four", "five", "six" ],
[ "seven", "height", "nine" ]
];
</pre>

This is especially useful when you want to display player names with colors. Example from "Hearts":
<pre>
$firstRow = [ '' ];
foreach( $players as $player_id => $player ) {
$cell = [ 'str' => '${player_name}',
'args' => [ 'player_name' => $player['player_name'] ],
'type' => 'header'
];
$firstRow[] = $cell;
}
$table[] = $firstRow;
...
</pre>

You can also use three extra attributes in the parameter array for the notification:
* '''header''': the content for this parameter displays before the table (also, the html will be parsed and player names will be colored according to the current game colors).
* '''footer''': the content for this parameter displays after the table (no parsing for coloring the player names)
* '''closing''': if this parameter is used, a button will be displayed with this label at the bottom of the popup and will allow players to close it (more easily than by clicking the top right 'cross' icon).

<pre>
$this->notifyAllPlayers( "tableWindow", '', [
"id" => 'finalScoring',
"title" => clienttranslate("Title of the scoring dialog"),
"table" => $table,
"header" => ['str' => clienttranslate('Table header with parameter ${number}'),
'args' => [ 'number' => 3 ],
],
"footer" => '<div class="myfoot"></div>',
"closing" => clienttranslate( "Closing button label" )
] );
</pre>

Note: currently id is not used - so you cannot access resulting div by id on js side
Note: any traslatable stirng have to be wrapped by clienttranslate() on top level OR it has to be recursive template.

DO NOT DO THIS:
<pre>
"footer" => '<div>'.clienttranslate( "The end" ).'</div>', // this will not work for translations!!!
</pre>

=== Scoring animated display ===

Sometimes, you may want to display a score value over an element to make the scoring easier to follow for the players (Terra Mystica final scoring for example).
You can do it with:

'''this.displayScoring(anchor_id: string, color: string, score: number | string, duration?: number, offset_x?: number, offset_y?: number): void'''

'''anchor_id''': ID of the html element to place the animated score onto (without the '#')

'''color''': hexadecimal RGB representation of the color (should be the color of the scoring player), but without a leading '#'. For instance, 'ff0000' for red.

'''score''': numeric score to display, prefixed by a '+' or '-'

'''duration''': animation duration in milliseconds (optional, default is 1000)

'''offset_x''' and '''offset_y''': if both offset_x and offset_y are defined and not null, apply the following offset (in pixels) to the scoring animation.
Note that the score is centered in the anchor, so the offsets might have to be negative if you calculate the position.

Note: if you want to display successively each score, you can use ''this.notifqueue.setSynchronous()'' function.
<pre>
setupNotifications: function() {
dojo.subscribe( 'displayScoring', this, "notif_displayScoring" );
...
}
...

notif_displayScoring: function(notif) {
const duration = notif.args.duration?notif.args.duration:1000;
this.notifqueue.setSynchronous('displayScoring', duration );
this.displayScoring( notif.args.target, notif.args.color, notif.args.score, duration);
},
</pre>

=== Speech bubble ===

For better interactivity in some games (Love Letter for example), you may use comic book style speech bubbles to express the players voices.
This is done with showBubble:

'''this.showBubble(anchor_id: string, text: string, delay?: number, duration?: number, custom_class?: string): void'''

* anchor_id - where to attach the bubble
* text - what to put in bubble, can be html
* delay - delay in milliseconds (optional, default 0)
* duration - duration of animation in milliseconds (optional, default 3000)
* custom_class - extra class to add to bubble (optional), if you need to override the default bubble style

<pre>
this.showBubble('meeple_2', _('Hello'), 0, 1000, 'pink_bubble');
</pre>

<pre>
notif_speechBubble(notif) {
var html = this.format_string_recursive(notif.args.text, notif.args.args);
this.showBubble(notif.args.target, html, notif.args.delay ?? 0, notif.args.duration ?? 1000);
},
</pre>

'''Warning''': if your bubble could overlap other active elements of the interface (buttons in particular), as it stays in place even after disappearing, you should use a custom class to give it the style "pointer-events: none;" in order to intercept click events.

Note: If you want this visually, but want to take complete control over this bubble and its animation (for example to make it permanent) you can just use div with 'discussion_bubble' class on it, and content of div is what will be shown.

== Translations ==

See [[Translations]]

== Players panels ==

=== Update players score ===

The column player_score from the player table is automatically loaded into this.scoreCtrl and therefore into the stars location on the player board. This occurs sometime after the game setup() function. However this score must be updated as the game progresses using notifications.

Note: this.scoreCtrl[player_id] is object of class [[Counter]], you can use other counter API.

Increase a player score (with a positive or negative number):

<pre>
this.scoreCtrl[ player_id ].incValue( score_delta );
</pre>

Set a player score to a specific value:

<pre>
this.scoreCtrl[ player_id ].setValue( new_score );
</pre>

Set a player score to a specific value with animation:

<pre>
this.scoreCtrl[ player_id ].toValue( new_score );
</pre>

Typical usage would be (that will process 'score' notification):
<pre>
setupNotifications : function() {
...
dojo.subscribe('score', this, "notif_score");
},
notif_score: function(notif) {
this.scoreCtrl[notif.args.player_id].setValue(notif.args.player_score);
},
</pre>

=== Adding stuff to player's panel ===

At first, create a new "JS template" string in your template (tpl) file:

(from Gomoku example)
<pre>
var jstpl_player_board = '\<div class="cp_board">\
<div id="stoneicon_p${id}" class="gmk_stoneicon gmk_stoneicon_${color}"></div><span id="stonecount_p${id}">0</span>\
</div>';
</pre>

Then, you add this piece of code in your JS file to add this template to each player panel:

<pre>
// Setting up player boards
for( var player_id in gamedatas.players )
{
var player = gamedatas.players[player_id];

// Setting up players boards if needed
var player_board_div = $('player_board_'+player_id);
dojo.place( this.format_block('jstpl_player_board', player ), player_board_div );
}
</pre>

(Note: the code above is of course from your "setup" function in your Javascript).

Very often, you have to distinguish current player and others players. In this case, you just have to create another JS template (ex: jstpl_otherplayer_board) and use it when "player_id" is different than "this.player_id".

=== Fixing Player Panel heights ===

You may find that the player panels don't automatically resize when adding something to (or removing something from) a player panel while the display is in portrait mode (i.e. the player summary panels are at the top of the screen rather than down the right side).

When this happens, call <pre>this.adaptPlayersPanels();</pre> This recalculates the layout and also adjusts the position of the actionbar for you.

=== Player's panel disabling/enabling ===

'''this.disablePlayerPanel(player_id: number): void'''

Disable given player panel (the panel background become gray).

Usually, this is used to signal that this played passes, or will be inactive during a while.

Note that the only effect of this is visual. There are no consequences on the behaviour of the panel itself.

'''this.enablePlayerPanel(player_id:number): void'''

Enable a player panel that has been disabled before.

'''this.enableAllPlayerPanels(): void'''

Enable all player panels that has been disabled before.

=== Player order ===

'''this.updatePlayerOrdering(): void'''

This function makes sure that player order in player's panel matches this.gamedatas.playerorder and its normally called by framework.
You can call it yoursel if you change this.gamedatas.playerorder from notification.
Also you can override this function to change defaults OR insert a non-player panel [[BGA_Studio_Cookbook#Inserting_non-player_panel]].

=== Counters ===
Note: there is bga component called "ebg/counter" this API is not using it, these methods
below declared right in core game. If you need animation for counters use ebg/counter

To use this API just create a counter dom element like this (class does not really matter)
<pre>
<div class="counter" id="bread"></div>
<div class="counter" id="coin"></div>
</pre>
The "bread" will the counter name.

The php code should send all "counters" data from getAllDatas() method like this

game.php
<pre>
protected function getAllDatas() {
// (the key must match counter_name)
$result['counters']=[
'bread' => [
'counter_name' => 'bread',
'counter_value' => 3
],
'coin' => [
'counter_name' => 'coin',
'counter_value' => 5
]
];
return $result;
}
</pre>

'''setCounter(counter_name: stirng, new_value: string | number): void'''

updates the global this.gamedatas.counters and value of node $(counter_name)
<pre>
notif_counter: function(notif) {
this.setCounter(notif.args.counter_name, notif.args.counter_value);
},
</pre>

'''incCounter(counter_name: string, delta: number): void'''
<pre>
notif_counter : function(notif) {
this.incCounter(notif.args.counter_name, notif.args.inc);
},
</pre>

'''updateCounters(counters: object): void'''

Useful for updating game counters in the player panel (such as resources).
'counters' arg is map of counters (the key must match counter_name)
{
'bread': {
'counter_name' : 'bread',
'counter_value' => 3
},
'coin': {
'counter_name' : 'coin',
'counter_value' => 5
}
}
All counters MUST be referenced in this.gamedatas.counters (means they should be send from php) and will be updated.
DOM objects referenced by 'counter_name' will have their innerHTML updated with 'counter_value'.

Usually you call this from notification

<pre>
notif_counter : function(notif) {
this.updateCounters(notif.args.counters);
},
</pre>

== BGA GUI components ==

BGA framework provides some useful ready-to-use components for the game interface:

[[Studio#BGA_Studio_game_components_reference]]

Note that each time you are using an additional component, you must declare it at the top of your Javascript file in the list of modules used.

Example if you are using "ebg.stock":
<pre>
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/stock" /// <=== we are using ebg.stock module
],
</pre>

== BGA Buttons ==

=== Basic Button ===

'''this.addActionButton(id: string, label: string, method: string | eventhandler, destination?: string, blinking?: boolean, color?: string): void'''

You can use this method to add an action button in the main action status bar (or other places).

Arguments:
* id: an element ID that should be unique in your HTML DOM document.
* label: the text of the button. Should be translatable (use _() function). Note: this can also be any html, such as "<div class='brick'></div>", see example below on how to make image action buttons.
* method: the name of your method that must be triggered when the player clicks on this button (can be name of the method on game class or handler).
* destination (optional): id of parent on where to add button, ONLY use in rare cases if location is not action bar. Use '''null''' as value if you need to specify other arguments.
* blinking (optional): if set to '''true''', the button is going blink to catch player's attention. Please DO NOT abuse blinking button. If you need button to blink after some time passed add class 'blinking' to the button later.
* color: could be '''blue''' (default), '''red''','''gray''' or '''none'''.

You should only use this method in your "onUpdateActionButtons" method. Usually, you use it like this:

<pre>
onUpdateActionButtons: function( stateName, args ) {
if (this.isCurrentPlayerActive()) {
switch( stateName ) {
case 'giveCards':
this.addActionButton( 'giveCards_button', _('Give selected cards'), 'onGiveCards' );
this.addActionButton( 'pass_button', _('Pass'), () => this.bgaPerformAction('actPass') );
break;
}
}
},
</pre>

In the example above, we are adding a "Give selected cards" button in the case we are on game state "giveCards". When player clicks on this button, it triggers our "onGiveCards" method.

Example using blinking red button:
<pre>
this.addActionButton( 'button_confirm', _('Confirm?'), 'onConfirm', null, true, 'red');
</pre>

If you want to call the handler with arguments, you can use arrow functions, like this:
<pre>
this.addActionButton( 'commit_button', _('Confirm'), () => this.onConfirm(this.selectedCardId), null, false, 'red');
</pre>

=== Image Button ===

You can use the same method, but add extra class to a button to disable the padding and style it, i.e.
<pre>
this.addActionButton( 'button_brick', '<div class="brick"></div>', ()=>{... on brick ...}, null, null, 'gray');
dojo.addClass('button_brick','bgaimagebutton');
</pre>

where

<pre>
.bgaimagebutton {
padding: 0px 12px;
min-height: 28px;
border: none;
}
</pre>

If you use this a lot, you can define a helper function, i.e.
<pre>
/**
* This method can be used instead of addActionButton, to add a button which is an image (i.e. resource). Can be useful when player
* need to make a choice of resources or tokens.
*/
addImageActionButton: function(id, div, handler, bcolor, tooltip) {
if (typeof bcolor == "undefined") {
bcolor = "gray";
}
// this will actually make a transparent button id color = gray
this.addActionButton(id, div, handler, null, false, bcolor);
// remove border, for images it better without
dojo.style(id, "border", "none");
// but add shadow style (box-shadow, see css)
dojo.addClass(id, "shadow bgaimagebutton");
// you can also add additional styles, such as background
if (tooltip) {
dojo.attr(id, "title", tooltip);
}
return $(id);
},
</pre>

=== Disabling Button ===

You can disable the '''bgabutton''' by adding the css class '''disabled''' in you js. The disabled button is still visible but is grey and not clickable.
For example in the '''onUpdateActionButtons''' :
<pre>
this.addActionButton('play_button_id', _('Play 1 to 3 cards'), 'playFunctionButton');
if (condition) {
dojo.addClass('play_button_id', 'disabled');
}
</pre>

=== Custom Buttons ===

You can create a custom button, but the BGA framework provides a standard button that requires only .css classes: '''bgabutton''' and '''bgabutton_${color}'''.

'''Examples:'''

<pre>
<a href="#" id="my_button_id" class="bgabutton bgabutton_blue"><span>My blue button</span></a>

<a href="#" id="my_button_id" class="bgabutton bgabutton_red bgabutton_big"><span>My big red button</span></a>
</pre>

'''Note''': To see it in action, check out ''Coloretto''.

=== Button outside of action bar ===

Use addActionButton() method with destination argument set
<pre>
this.addActionButton( 'commit_button', _('Confirm'), 'onConfirm', 'player_board', true, 'red');
</pre>

in example above the button will be place on object with id 'player_board'

== Image loading ==

See also [[Game_art:_img_directory]].

'''Be careful''': by default, ALL images of your img directory are loaded on a player's browser when he loads the game. For this reason, don't let in your img directory images that are not useful, otherwise it's going to slowdown the game load.

'''this.dontPreloadImage(image_file_name: string)'''

Using dontPreloadImage, you tell the interface to not preload a specific image in your img directory.

Example of use:
<pre>
this.dontPreloadImage( 'cards.png' );
</pre>

This is particularly useful if for example you have 2 different themes for a game. To accelerate the loading of the game, you can specify to not preload images corresponding to the other theme.

Another example of use: in "Gosu" game with Kamakor extension, you play with 5 sets of cards among 10 available. Cards images are organized by sets, and we only preload the images corresponding to the 5 current sets with '''ensureSpecificGameImageLoading( image_file_names_array )'''.
<pre>
// By default, do not preload anything
this.dontPreloadImage( 'cards.png' );
this.dontPreloadImage( 'clan1.png' );
this.dontPreloadImage( 'clan2.png' );
this.dontPreloadImage( 'clan3.png' );
this.dontPreloadImage( 'clan4.png' );
this.dontPreloadImage( 'clan5.png' );
this.dontPreloadImage( 'clan6.png' );
this.dontPreloadImage( 'clan7.png' );
this.dontPreloadImage( 'clan8.png' );
this.dontPreloadImage( 'clan9.png' );
this.dontPreloadImage( 'clan10.png' );
var to_preload = [];
for( i in this.gamedatas.clans )
{
var clan_id = this.gamedatas.clans[i];
to_preload.push( 'clan'+clan_id+'.png' );
}

this.ensureSpecificGameImageLoading( to_preload );

</pre>

'''Note:''' You don't need to specify to not preload game box images (game_box.png, game_box75.png...) since they are not preloaded by default.

'''this.ensureSpecificGameImageLoading(list: string[])'''

This is oppostive of dontPreloadImage - its ensure specific images is loaded. Note: only makes sense if preload list is empty, otherwise everything is loaded anyway

'''load specific images'''
All images that will be preloaded stored in g_img_preload. If you want to override it directly - there is no API, but you can do this in GAME constructor

g_img_preload = ['tokens.png', 'trains.png', 'loc_plan.png', 'eng.png', 'eng-back.png'];

You can also set it to empty array and call ensureSpecificGameImageLoading() on specific images

== Sounds ==

Add a custom sound and make it load with your interface:

Add this in your template (.tpl) file:
<pre>
<audio id="audiosrc_<gamename>_<yoursoundname>" src="{GAMETHEMEURL}img/<gamename>_<yoursoundname>.mp3" preload="none" autobuffer></audio>
<audio id="audiosrc_o_<gamename>_<yoursoundname>" src="{GAMETHEMEURL}img/<gamename>_<yoursoundname>.ogg" preload="none" autobuffer></audio>
</pre>

Note: this is a requirement to provide both a mp3 and a ogg file with the names <code><gamename>_<yoursoundname>[.ogg][.mp3]</code>.

Play the sound (from your .js file):

<pre>
playSound('<gamename>_<yoursoundname>'); // do not add 'this.' - its a global function
</pre>

Disable the standard "move" sound for this move (to replace it with your custom sound):

Add this to your notification handler:

<pre>
this.disableNextMoveSound();
</pre>

Note: it only disable the sound for the next move.

== Title bar and states ==

=== Client states ===

Client states is a way to simulate the state transition but without actually going
to server. It is usefull when you need to ask user multiple questions before you
send things to server

'''this.setClientState(newState: string, args: object)'''

Example:
this.setClientState("client_playerPicksLocation", {
descriptionmyturn : _("${you} must select location"),
});

For more information see [[BGA_Studio_Cookbook#Multi_Step_Interactions:_Select_Worker.2FPlace_Worker_-_Using_Client_States]]

'''this.restoreServerGameState()'''
If you are in client state it will restore the current server state (cheap undo)

'''this.on_client_state'''
Boolean indicating that we are in client state

=== Title bar ===
If you simply want to show something in title bar you can do it directly
$('pagemaintitletext').innerHTML = text;

This however will not work with parameters and will not draw You in color,
if you want to do proper args rendering use method below

;'''this.removeActionButtons()'''
Removes all buttons from title bar

;'''this.updatePageTitle()'''
:This function allows to update the current page title and turn description according to the game state arguments. If the current game state description this.gamedatas.gamestate.descriptionmyturn is modified before calling this function it allows to update the turn description without changing state. This will handle arguments substitutions properly.

Note: this functional also will calls this.onUpdateActionButtons, if you want different buttons then state defaults, use method in example to replace them, if it becomes too clumsy use client states (see above)

Example from Terra Mystica:
<pre>
onClickFavorTile: function( evt ) {
...
if ( ... ) {
this.gamedatas.gamestate.descriptionmyturn = _('Special action: ') + _('Advance 1 space on a Cult track');
this.updatePageTitle();
this.removeActionButtons();
this.addActionButton( ... );
...
return;
}
...

}
</pre>

== User preferences ==
'''this.getGameUserPreference(pref_id)'''

Return the value of a user preference. It will return the value currently selected in the select combo box, in the top-right menu.

'''this.setGameUserPreference(pref_id, value)'''

Programmatically change a user preference. It will have the same effect as if the player changed the value in the select combo box, in the top-right menu.

'''this.onGameUserPreferenceChanged'''

A callback you can define if you want to be notified when a user changes a user preference.

Example:<pre>
onGameUserPreferenceChanged: function(pref_id, pref_value) {
switch (pref_id) {
case 201:
document.getElementsByTagName('html')[0].classList.toggle('dark-background', pref_value == 2);
break;
}
}
</pre>

== Other useful stuff ==

'''dojo.hitch'''

With dojo.hitch, you can create a callback function that will run with your game object context whatever happen.

Typical example: display a BGA confirmation dialog with a callback function created with dojo.hitch:

<pre>
this.confirmationDialog( _('Are you sure you want to make this?'), dojo.hitch( this, function() {
this.bgaPerformAction('makeThis');
} ) );
</pre>

In the example above, using dojo.hitch, we ensure that the "this" object will be set when the callback is called.

NOTE: In modern JS there are lambdas that eliminate need for that, the example above will look like this
<pre>
this.confirmationDialog( _('Are you sure you want to make this?'), () => this.bgaPerformAction( 'makeThis') );
</pre>

;'''onScreenWidthChange()'''
:This function can be overridden in your game to manage some resizing on the client side when the browser window is resized. This function is also triggered at load time, so it can be used to adapt to the :viewport size at the start of the game too.

; this.bRealtime
: Return true if the game is in realtime. Note that having a distinct behavior in realtime and turn-based should be exceptional.

; g_replayFrom
: Global contains replay number in live game, it is set to undefined (i.e. not set) when it is not a replay mode, so consequentially the good check is '''typeof g_replayFrom != 'undefined'''' which returns true if the game is in replay mode <i>during the game</i> (the game is ongoing but the user clicked "replay from this move" in the log)

; g_archive_mode
: Returns true if the game is in archive mode <i>after the game</i> (the game has ended)

; this.instantaneousMode
: Returns true during replay/archive mode if animations should be skipped. Only needed if you are doing custom animations. (The BGA-provided animation functions like <i>this.slideToObject()</i> automatically handle instantaneous mode.)
: Technically, when you click "replay from move #20", the system replays the game from the very beginning with moves 0 - 19 happening in instantaneous mode and moves 20+ happening in normal mode.

; g_tutorialwritten
: Returns an object like the below if the game is in tutorial mode, or undefined otherwise. Tutorial mode is a special case of archive mode where comments have been added to a previous game to teach new players the rules.
{
author: "91577332",
id: "576",
mode: "view"
status: "alpha"
version_override: null
viewer_id: "84554161"
}

'''getBgaEnvironment(): string'''
: Returns "studio" for studio and "prod" for production environment (i.e. where games current runs). Only useful for debbugging hooks.
Note: alpha server is also "prod"

[[Category:Studio]]

Game interface logic: Game.js

2024-09-25T16:47:37Z

Sguzzer Gunayer: /* Creating and Destroying elements */

{{Studio_Framework_Navigation}}

__TOC__

This is the main file for your game interface. Here you will define:

* Which actions on the page will generate calls to the server.
* What happens when you get a notification for a change from the server and how it will show in the browser.
* Setup user interface

== File structure ==

The details of how the file is structured are described below with comments in the code skeleton provided to you.

Here is the basic structure:

* '''constructor''': here you can define global variables for your whole interface.
* '''setup''': this method is called when the page is refreshed, and sets up the game interface.
* '''onEnteringState''': this method is called when entering a new game state. You can use it to customize the view for each game state.
* '''onLeavingState''': this method is called when leaving a game state.
* '''onUpdateActionButtons''': called on state changes, in order to add action buttons to the status bar. Note: in a multipleactiveplayer state, it will be called when another player has become inactive.
* ''(utility methods)'': this is where you can define your utility methods.
* ''(player's actions)'': this is where you can write your handlers for player actions on the interface (example: click on an item).
* '''setupNotifications''': this method associates notifications with notification handlers. For each game notification, you can trigger a javascript method to handle it and update the game interface.
* ''(notification handlers)'': this is where you define the notifications handlers associated with notifications in '''setupNotifications''', above.

More details:

'''setup(gamedatas: object) '''
This method must set up the game user interface according to current game situation specified in parameters.
The method is called each time the game interface is displayed to a player, ie:

* when the game starts
* when a player opens a game in the browser later
* when a player refreshes the game page (F5)
* when player does a server side Undo

"gamedatas" argument contains all data retrieved by your "getAllDatas" PHP method and some more.

'''onEnteringState(stateName: string, args: { args: any } | null): void'''

This method is called each time we enter a new game state.
You can use this method to perform some user interface changes at this moment.
To access state arguments passed via calling php arg* method use args?.args.
Typically you would do something only for active player, using this.isCurrentPlayerActive() check.
It is also called (for the current game state only) when doing a browser refresh (after the setup method is called).

'''Warning''': for multipleactiveplayer states:
the active players are NOT active yet so you must use onUpdateActionButtons to perform the client side operation which depends on a player active/inactive status.
If you are doing initialization of some structures which do not depend on the active player, you can just replace (this.isCurrentPlayerActive()) with (!this.isSpectator)
for the main switch in that method.

See more details in [[Your_game_state_machine:_states.inc.php#Difference_between_Single_active_and_Multi_active_states]]

'''onLeavingState(stateName: string): void'''

This method is called each time we leave a game state.
You can use this method to perform some user interface changes at this point (i.e. cleanup).

'''onUpdateActionButtons(stateName: string, args: object | null): void'''

In this method you can manage "action buttons" that are displayed in the action status bar and highlight active UI elements.
To access state arguments passed via calling php arg* method use '''args''' parameter. Note: args can be null! For '''game''' states and when you don't supply state args function - it is null.
This method is called when the active or multiactive player changes. In a classic "activePlayer" state this method is called before the onEnteringState state.
In multipleactiveplayer state it is a mess. The sequencing of calls depends on whether you get into that state from transitions OR from reloading the whole game (i.e. F5).

See more details in [[Your_game_state_machine:_states.inc.php#Difference_between_Single_active_and_Multi_active_states]]

== Dojo framework ==

BGA uses the [http://dojotoolkit.org/ Dojo Javascript framework].

The Dojo framework allows us to do complex things more easily. The BGA framework uses Dojo extensively.

To implement a game, you only need to use a few parts of the Dojo framework. All the Dojo methods you need are described on this page.

== Javascript minimization (after July 2020) ==

For performance reasons, when deploying a game the javascript code is minimized using '''terser''' (https://github.com/terser/terser). This minifier works with modern javascript syntax. From your project "Manage game" page, you can now test a minified version of your javascript on the studio (and revert to the original).

NB: it has been reported that there is an issue with this minifier and percentage values for opacity.

== Accessing Players Information ==

'''this.player_id: number'''
id of the player who is looking at the game. The player may not be part of the game (i.e. spectator)
if (notif.args.player_id == this.player_id) {
...
}

'''this.isSpectator: boolean'''
Flag set to true if the user at the table is a spectator (not a player).

Example:
<pre>
if (this.isSpectator) {
this.player_color = 'ffffff';
} else {
this.player_color = gamedatas.players[this.player_id].color;
}
</pre>

Note: If you want to hide an element from spectators, you should use [[Game_interface_stylesheet:_yourgamename.css#spectatorMode|CSS 'spectatorMode' class]].

You may consider making a function like this, to detect if the game is in a read-only state (i.e. non-interactive):
// Returns true for spectators, instant replay (during game), archive mode (after game end)
isReadOnly: function () {
return this.isSpectator || typeof g_replayFrom != 'undefined' || g_archive_mode;
}

'''this.gamedatas: object'''
Contains the initial set of data to init the game, created at game start or by game refresh (F5).
You can update it as needed to keep an up-to-date reference of the game on the client side if you need it, however most of the time this is unnecessary.

Note: In hotseat mode, the framework does not keep this.gamedatas of hotseat players and shares the same set as the main player to store data.

Note: be careful when you update this data structurally, many framework functions expect data to be certain way and they will break if they see something else.

Typical example of accessing player's info
<pre>
for (var player_id in this.gamedatas.players) {
var playerInfo = this.gamedatas.players [player_id];
var c = playerInfo.color;
var name = playerInfo.name;
// do something
}
</pre>

'''this.isCurrentPlayerActive(): boolean'''
Returns true if the player on whose browser the code is running is currently active (it's his turn to play). Note: see remarks above about usage of this function inside onEnteringState method.
if (this.isCurrentPlayerActive()) ...

'''this.getActivePlayerId(): number'''
Return the ID of the active player, or null if we are not in an "activeplayer" type state.
if (this.player_id == this.getActivePlayerId()) ...

'''this.getActivePlayers(): number[]'''
Return an array with the IDs of players who are currently active (or an empty array if there are none).

== Accessing and manipulating the DOM ==

=== Element by Id ===

'''$(elementId: ElementOrId)'''

The $ function is used to get an HTML element using its "id" attribute.

Example: modify the content of a "span" element:

<pre>
In your HTML code:
<span id="a_value_in_the_game_interface">1234</span>

In your Javascript code:
$('a_value_in_the_game_interface').innerHTML = "9999";
</pre>

Note: It is safe to use if you don't know if variable is string (id of element) or element itself, i.e.
<pre>
foo: function(card) {
card = $(card); // now its node, no need to write if (typeof card === 'string') ...
// but its good idea to check for null here
...
}
</pre>

'''getElementById(elementId: string)'''

Note: $() is the standard method to access some HTML element with the BGA Framework. You can use '''getElementById''' but it is longer to type and less handy as it does not do some checks.

=== Style ===

'''dojo.style(node: ElementOrId, styleName: string, styleValue: any): void'''

With dojo.style you can modify the CSS property of any HTML element in your interface.

Examples:

<pre>
// Make an element disappear
dojo.style( 'my_element', 'display', 'none' );

// Give an element a 2px border
dojo.style( 'my_element', 'borderWidth', '2px' );

// Change the background position of an element
// (very practical when you are using CSS sprites to transform an element to another)
dojo.style( 'my_element', 'backgroundPosition', '-20px -50px' );
</pre>

Note: if you have to modify several CSS properties of an element, or if you have a complex CSS transformation to do, you should consider using dojo.addClass/dojo.removeClass (see below).

You can also use object to set multiple values
<pre>
dojo.setStyle("thinger", {
"opacity": 0.5,
"border": "3px solid black",
"height": "300px"
});
</pre>

'''this.addStyleToClass(cssClassName: string, styleName: string, styleValue: any):''' '''void'''

Same as dojo.style(), but for all the nodes set with the specified cssClassName
Equivalent of

dojo.query(`.${aclass}`).style(styleName, styleValue)

<pre>
dojo.query("#baz > div").style({
opacity:0.75,
fontSize:"13pt"
});
</pre>

'''Vanilla JS style'''
$('my_element').style.display='none'; // set
var display = $('my_element').style.display; // get
$('my_element').style.removeProperty('display'); // remove

=== Classes ===

'''dojo.addClass(node: ElementOrId, classes: string): void'''

'''dojo.removeClass(node: ElementOrId, classes: string): void'''

'''dojo.hasClass(node: ElementOrId, aclass: string): void'''

'''dojo.toggleClass(node: ElementOrId, aclass: string): void'''

In many situations, many small CSS property updates can be replaced by a CSS class change (i.e., you add a CSS class to your element instead of applying all modifications manually).

Advantages are:
* All your CSS stuff remains in your CSS file.
* You can add/remove a list of CSS modifications with a simple function and without error.
* You can test whether you applied the CSS to an element with the '''dojo.hasClass''' method.

Example from ''Reversi'':

<pre>
// We add "possibleMove" to an element
dojo.addClass( 'square_'+x+'_'+y, 'possibleMove' );

// In our CSS file, the class is defined as:
.possibleMove {
background-color: white;
opacity: 0.2;
filter:alpha(opacity=20); /* For IE8 and earlier */
cursor: pointer;
}

// So we've applied 4 CSS property changes in one line of code.

// ... and when we need to check if a square is a possible move on the client side:
if( dojo.hasClass( 'square_'+x+'_'+y, 'possibleMove' ) )
{ ... }

// ... and if we want to remove all possible moves in one line of code (see "dojo.query" method):
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );
</pre>

'''Vanilla JS classList'''

This is the only exception where dojo versions are better
// add class
$(token_id).classList.addClass('possibleMove');
// remove class
$(token_id).classList.removeClass('possibleMove');
// add 2 classes
const myclasses = ['a','b'];
$(token_id).classList.addClass(...myclasses);
// add classes to query result
document.querySelectorAll(".hand .card").forEach((node)=>node.classList.addClass('possibleMove'));

=== Attributes ===

;dojo.attr

With dojo.attr you can access or change the value of an attribute or property of any HTML element in your interface.

Exemple:
<pre>
// Get the title of a node
var title = dojo.attr( id, 'title' );
// Change the height of a node
dojo.attr( 'img_growing_tree', 'height', 100 );
</pre>

'''Vanilla JS attr'''

$(token).id=new_id; // set attr for "id"
var id = $(token).id; // get

=== Queries ===

'''dojo.query(cssSelector: string): Element[]'''

With dojo.query, you can query a bunch of HTML elements with a single function, with a "CSS selector" style.

Example:
<pre>
// All elements with class "possibleMove":
var elements = dojo.query( '.possibleMove' );

// Count number of tokens (i.e., elements of class "token") on the board (i.e., the element with id "board"):
dojo.query( '#board .token' ).length;
</pre>

But what is really cool with dojo.query is that you can combine it with almost all methods above.

Examples:
<pre>
// Trigger a method when the mouse enter in any element with class "meeple":
dojo.query( '.meeple' ).connect( 'onmouseenter', this, 'myMethodToTrigger' );

// Hide all meeples who are on the board
dojo.query( '#board .meeple' ).style( 'display', 'none' );
</pre>

'''Vanilla JS query'''

var cards=document.querySelectorAll(".hand .card");// all cards in all hands
var cards=$('hand').querySelectorAll(".card");// all cards in specific hand
var card=document.querySelector(".hand .card");// first card or null if none (super handy)

=== Creating and Destroying elements ===

'''dojo.empty(node: ElementOrId)'''

Remove all children of the node element
dojo.empty('my_hand');

'''dojo.destroy(node: ElementOrId)'''

Remove the element
dojo.destroy('my_token');

dojo.query(".green", mynode).forEach(dojo.destroy); // this remove all subnode of class green from mynode

'''dojo.create(tag: string, attributes?: obj, parent?: ElementOrId): Element'''

Create element

dojo.create("div", { class: "yellow_arrow" }, parent); // this creates div with class yellow_array and places it in "parent"

'''this.format_block(name: string, args: object): string'''

This bga function that takes global var from template file and substitute variables, typical use would be

var player = gamedatas.players[player_id];
var div = this.format_block('jstpl_player_board', player ); // var jstpl_player_board = ... is defined in .tpl file
Note: result is trimmed

'''this.format_string(name: string, args: object): string'''

This bga function just substitute variables in a string, i.e.
<pre>
var div = this.format_string('<div color="${player_color}"></div>', {player_color: '#ff0000'} );
</pre>
Note: result is trimmed

Note: this can be replaced by using backquoted string now:
const player_color = '#ff0000';

const div = ``;
'''this.format_string_recursive'''

This bga function is similar to this.format_string but is capable of processing recursive argument structures and translations. It is used to format server notifications.

TODO: find better place for these function docs

=== Moving elements ===

'''dojo.place(node: string | Element, refNode: ElementOrId, pos?: string | number): Element'''

dojo.place is the best function to insert HTML code somewhere in your game interface without breaking something. It is much better to use than the '''innerHTML=''' method if you must insert HTML tags and not only values.

node:

Can be a String or a DOM node. If it is a string starting with “<”, it is assumed to be an HTML fragment, which will be created. Otherwise it is assumed to be an id of a DOM node.

<pre>
// Insert your HTML code as a child of a container element
dojo.place( "<div class='foo'></div>", "your_container_element_id" );
</pre>

pos:

Optional argument. Can be a number or one of the following strings: “before”, “after”, “replace”, “only”, “first”, or “last”. If omitted, “last” is assumed.

"replace": Replace the container element with my_node element

"first": Places the node as a child of the reference node. The node is placed as the first child.

"last" (default): Places the node as a child of the reference node. The node is placed as the last child.

"before": places the node right before the reference node.

"after": places the node right after the reference node.

"only": replaces all children of the reference node with the node.

positive integer: This parameter can be a positive integer. In this case, the node will be placed as a child of the reference node with this number (counting from 0). If the number is more than number of children, the node will be appended to the reference node making it the last child.

<pre>
// Replace all children of container with my_node
dojo.place( $('my_node'), "your_container_element_id", "only" );
</pre>

See also full doc on dojo.place: [https://dojotoolkit.org/reference-guide/1.7/dojo/place.html]

Usually, when you want to insert some piece of HTML in your game interface, you should use "[[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl#Javascript_templates|Javascript templates]]".

But you can also relocate elements like that. Note: it won't animate if you do that.

'''this.placeOnObject(mobile_obj: ElementOrId, target_obj: ElementOrId): void'''

places mobile_obj on target_obj, set the absolute positions and centers the mobile_obj on target_obj,
effect is immediate

This is not really an animation, but placeOnObject is frequently used before starting an animation.

Example:
<pre>
// (We just created an object "my_new_token")

// Place the new token on current player board
this.placeOnObject( "my_new_token", "overall_player_board_"+this.player_id );

// Then slide it to its position on the board
this.slideToObject( "my_new_token", "a_place_on_board" ).play();
</pre>

'''this.placeOnObjectPos(mobile_obj: ElementOrId, target_obj: ElementOrId, target_x: number, target_y: number): void'''

This method works exactly like placeOnObject, except than you can specify some (x,y) coordinates (in px). This way, the center of "mobile_obj" will be placed to the specified x,y position relatively to the center of "target_obj".

''Note: the placement works differently from this.slideToObjectPos'', since coordinates are calculated based on the center of objects.

'''this.attachToNewParent(mobile_obj: ElementOrId, target_obj: ElementOrId): void'''

With this method, you change the HTML parent of "mobile_obj" element without moving it.
"target_obj" is the new parent of this element. The beauty of
attachToNewParent is that the mobile_obj element DOES NOT MOVE during this process.

What happens is that the method calculate a relative position of mobile_obj to make sure it does not move after the HTML parent changes.

Why using this method?

Changing the HTML parent of an element can be useful for the following reasons:
* When the HTML parent moves, all its child are moving with them. If some game elements is no more linked with a parent HTML object, you may want to attach it to another place.
* The z_order (vertical order of display) depends on the position in the DOM, so you may need to change the parent of some game elements when they are moving in your game area.

'''CAREFUL''': this function destroys original object and places a clone onto a new parent, this will break all references to this HTML element (ex: dojo.connect).
If you need version that does not destroy the object but the same otherwise see [[BGA_Studio_Cookbook#Attach_to_new_parent_without_destroying_the_object]]

== Animations ==

===Dojo Animations===

BGA animations is based on Dojo Animation ([http://dojotoolkit.org/documentation/tutorials/1.8/animation/ see tutorial here]).

However, most of the time, you can just use methods below, which are built on top of Dojo Animation.

Note: one interesting method from Dojo that could be useful from time to time is "Dojo.Animation". It allows you to make any CSS property "slide" from one value to another.

Note 2: the slideTo methods are not compatible with CSS transform (scale, zoom, rotate...). If possible, avoid using CSS transform on nodes that are being slided. Eventually, the only possible solution to make these 2 compatible is to disable all CSS transform properties, use slideToObjectPos/placeOnObjectPos, and then apply them again.

===Sliding===

'''this.slideToObject(mobile_obj: ElementOrId, target_obj: ElementOrId, duration?: number, delay?: number): Animation'''

You can use slideToObject to "slide" an element to a target position.

Sliding element on the game area is the recommended and the most used way to animate your game interface. Using slides allow players to figure out what is happening on the game, as if they were playing with the real boardgame.

The parameters are:
* mobile_obj: the ID of the object to move. This object must be "relative" or "absolute" positioned.
* target_obj: the ID of the target object. This object must be "relative" or "absolute" positioned. Note that it is not mandatory that mobile_obj and target_obj have the same size. If their size are different, the system slides the center of mobile_obj to the center of target_obj.
* duration: (optional) defines the duration in millisecond of the slide. The default is 500 milliseconds.
* delay: (optional). If you defines a delay, the slide will start only after this delay. This is particularly useful when you want to slide several object from the same position to the same position: you can give a 0ms delay to the first object, a 100ms delay to the second one, a 200ms delay to the third one, ... this way they won't be superposed during the slide.

BE CAREFUL: The method returns an dojo.fx animation, so you can combine it with other animation if you want to. It means that you have to call the "play()" method, otherwise the animation WON'T START.

Example:
<pre>
this.slideToObject( "some_token", "some_place_on_board" ).play();
</pre>

'''this.slideToObjectPos(mobile_obj: ElementOrId, target_obj: ElementOrId, target_x: number, target_y: number, duration?: number, delay?: number): Animation'''

This method does exactly the same as "slideToObject", except than you can specify some (x,y) coordinates. This way, "mobile_obj" will slide to the specified x,y position relatively to "target_obj".

Example: slide a token to some place on the board, 10 pixels from the top:
<pre>
this.slideToObjectPos( "some_token", "some_place_on_board", 0, 10 ).play();
</pre>

'''this.slideTemporaryObject(mobile_obj_html: string, parent: ElementOrId, from: ElementOrId, to: ElementOrId, duration?: number, delay?: number): Animation'''

This method is useful when you want to slide a temporary HTML object from one place to another. As this object does not exists before the animation and won't remain after, it could be complex to create this object (with dojo.place), to place it at its origin (with placeOnObject) to slide it (with slideToObject) and to make it disappear at the end.

slideTemporaryObject does all of this for you:
* mobile_obj_html is a piece of HTML code that represent the object to slide.
* parent is the ID of an HTML element of your interface that will be the parent of this temporary HTML object.
* from is the ID of the origin of the slide.
* to is the ID of the target of the slide.
* duration/delay works exactly like in "slideToObject"

Example:
<pre>
this.slideTemporaryObject( '<div class="token_icon"></div>', 'tokens', 'my_origin_div', 'my_target_div' ).play();
</pre>

===Destroy===
'''this.slideToObjectAndDestroy(mobile_obj: ElementOrId, target_obj: ElementOrId, duration?: number, delay?: number): void'''

This method is a handy shortcut to slide an existing HTML object to some place then destroy it upon arrival. It can be used for example to move a victory token or a card from the board to the player panel to show that the player earns it, then destroy it when we don't need to keep it visible on the player panel.

It works the same as this.slideToObject and takes the same arguments, but it starts the animation.

CAREFUL: Make sure nothing is creating the same object at the same time the animation is running, because this will cause some random disappearing effects

Example:
<pre>
this.slideToObjectAndDestroy( "some_token", "some_place_on_board", 1000, 0 );
</pre>

'''this.fadeOutAndDestroy( node: string | Element, duration?: number, delay?: number):''' '''void'''

This function fade out the target node, then destroy it. Its starts the animation.
* duration/delay works exactly like in "slideToObject"

Example:
<pre>
this.fadeOutAndDestroy( "a_card_that_must_disappear" );
</pre>

CAREFUL: the HTML node still exists until during few milliseconds, until the fadeOut has been completed.
Make sure nothing is creating same object at the same time as animation is running, because you will be some random dissapearing effects

===Rotating elements===

This example combines "Dojo.Animation" method and a CSS property transform that allow you to rotate the element.
<pre>
// node is Element we rotating
var animation = new dojo.Animation({
curve: [fromDegree, toDegree],
onAnimate: (v) => {
node.style.transform = 'rotate(' + v + 'deg)';
}
});

animation.play();
</pre>

BGA has its own interface to rotate

'''this.rotateTo(node: string | Element, degree: number): void'''

It starts the animation, and stored the rotation degree in the class, so next time you rotate object - it is additive.
There is no animation hooks in this one, if you need to change any parameters use dojo animation above.

There is also '''rotateInstantTo''' with same signature which does not animate

===Animation Callbacks===

If you wish to run some code only after an animation has completed you can do this by linking a callback method to 'onEnd'.

<pre>
var animation_id = this.slideToObject( mobile_obj, target_obj, 500 );
dojo.connect(animation_id, 'onEnd', () => {
// do something here
});
animation_id.play();
</pre>

If you wish to call a second animation after the first (rather than general code) then you can use a dojo animation chain (see tutorial referenced above).

== Players input ==

=== Connecting ===
'''dojo.connect(element: Element, event: string, context: object, method: eventHandler): any'''

'''dojo.connect(element: Element, event: string, hander: eventHandler): any'''

Used to associate a player event with one of your notification methods.

Example: associate a click on an element ("my_element") with one of our methods ("onClickOnMyElement"):
<pre>
dojo.connect( $('my_element'), 'onclick', this, 'onClickOnMyElement' );
</pre>

Same idea but base on query (i.e. all element of 'pet' class)
dojo.query(".pet").connect('onclick', this, 'onPet');

Note: if you need to disconnect the handler you have to store handler returned from this method, i.e.

<pre>
var handler = dojo.connect(...);
...
dojo.disconnect(handler);
</pre>

If you don't store the handler - you have to destroy the object to disconnect it

Typical function that implements the input handler will look like this

<pre>
onPet: function(event) {
var id = event.currentTarget.id;
console.log('onPet ' + id);
dojo.stopEvent(event);
if (this.gamedatas.gamestate.name == 'playerTurnPet') {
this.bgaPerformAction('actPlayPet', {card: id});
} else {
this.showMoveUnauthorized();
}
}
</pre>

'''this.connect(element: ElementOrId, event: string, method: eventHandler): void'''

Used to associate a player event with one of your notification methods.

this.connect( $('my_element'), 'onclick', 'onClickOnMyElement' );

Or you can use an in-place handler

this.connect( $('my_element'), 'onclick', (e) => { console.log('boo'); } );

Note that this function stores the connection handler. That is the only real difference between '''this.connect''' and '''dojo.connect'''. If you plan to destroy the element you connected, you '''must''' call this.disconnect() to prevent memory leaks.
This function is mainly for permanent objects - if you just want to connect the temp object you should probably not use this method but use dojo.connect which won't require any clean-up.

'''this.connectClass(cssClassName: string, event: string, method: eventHandler): void'''

Same as connect(), but for all the nodes set with the specified cssClassName.

this.connectClass('pet', 'onclick', 'onPet');

'''this.disconnect(element: ElementOrId, event: string): void'''

Disconnect event handler (previously registered with this.connect or this.connectClass).

this.disconnect( $('my_element'), 'onclick');

Note: dynamic connect/disconnect is for advanced cases ONLY, you should always connect elements statically if possible, i.e. in setup() method.

'''this.disconnectAll(): void'''

Disconnect all previously registed event handlers (registered via this.connect or this.connectClass)

this.disconnectAll();

=== Actions ===

'''this.bgaPerformAction(action: string, args?: object, options: object = { lock: true, checkAction: true }): Promise<void>'''

Triggers an action on the backend. This is a combination of checkAction and ajaxcall, returning a Promise which resoves when ajaxcall ends.

This method must be used to send a player input to the game server. '''It should not be triggered programmatically''', especially not in loops, in callbacks, in notifications, or in onEnteringState/onUpdateActionButtons/onLeavingState, in order not to create race conditions or break replay game and tutorial features. It should be used only in reaction to a user action in the interface.

* action: name of the action, as it is written in "possibleactions" of the current state.
* args: an object containing the call parameters to send to the action
* options: options to tweak the call with some defaults. Default is <code>{ lock: true, checkAction: true }</code>.

Example of a standard call without args:
this.bgaPerformAction('pass');

Example of a standard call with action args:
this.bgaPerformAction('actPlayCard', { id: this.selectedCardId });

Example of a call without checking action (because player is inactive in a multiactive state):

this.bgaPerformAction('actChangeMind', {}, { checkAction: false });

Example of a call without lock (because of a special action not directly related to the game flow):

this.bgaPerformAction('actSetAutoBid', { alwaysBidUntil: 500 }, { lock: false, checkAction: false });

Example of call with reaction to exception:
this.bgaPerformAction('actPlayCard', { id: this.selectedCardId }).catch(()=>{ this.selectedCardId = undefined; });

Example of call with reaction to success:
this.bgaPerformAction('actPlayCard', { id: this.selectedCardId }).then(()=>{ this.unselectAll(); });

'''this.ajaxcall(url, parameters, obj_callback, callback, callback_anycase?, ajax_method?: string)'''

''Note: bgaPerformAction is a simpler way to use ajax calls, ajaxcall stays in the doc for legacy reasons only and should not be used in new projects.''

Same warning as '''this.bgaPerformAction''' about using on user action only.

* url: the url of the action to perform. For a game, it must be: "/<mygame>/<mygame>/myAction.html"
* parameters: an array of parameter to send to the game server.
** Note that "lock: true" must always be specified in this list of parameters in order the interface can be locked during the server call. Cannot use lock: false - to not lock it has to be undefined.
** Note: Restricted parameter names (please don't use them):
*** "action"
*** "module"
*** "class"
* obj_callback: must be set to "this".
* callback (non-optional but rarely used): a function to trigger when the server returns result and everything went fine (not used, as all data handling is done via notifications).
* callback_anycase: (optional) a function to trigger when the server returns ok OR error. If no error this function is called with parameter value false. If an error occurred, the first parameter will be set to true, the second will contain the error message sent by the PHP back-end, and the third will contain an error code.
* ajax_method: (optional and rarely used) if you need to send large amounts of data (over 2048 bytes), you can set this parameter to 'post' (all lower-case) to send a POST request as opposed to the default GET. This works, but was not officially documented, so only use if you really need to.

Usage:
<pre>
this.ajaxcall( '/mygame/mygame/actMyAction.html', { lock: true,
arg1: myarg1,
arg2: myarg2
}, this, (result)=>{} );
</pre>

'''this.checkAction(action: string, nomessage?: boolean): boolean '''

Check if player can do the specified action by taking into account:
* if interface is locked it will return false and show message "An action is already in progress", unless nomessage set to true
* if player is not active it will return false and show message "This is not your turn", unless nomessage set to true
* if action is not in list in possible actions (defined by "possibleaction" in current game state) it will return false and show "This move is not authorized now" error (unconditionally).
* otherwise returns true
Example:
<pre>
function onClickOnGameElement( evt ) {
if( this.checkAction( "actMyAction" ) ) {
// Do the action
}
}
</pre>

'''this.checkPossibleActions(action: string): boolean'''

* this is independent of the player being active, so can be used instead of this.checkAction(). This is particularly useful for multiplayer states when the player is not active in a 'player may like to change their mind' scenario. Unlike this.checkAction, this function does NOT take interface locking into account

* if action is not in list in possible actions (defined by "possibleaction" in current game state) it will return false and show "This move is not authorized now" error (unconditionally).
* otherwise returns true

function onChangeMyMind( evt ) {
if( this.checkPossibleActions( "actMyAction" ) ) {
// Do the action
}
}

'''this.checkLock(nomessage?: boolean): boolean'''

When using "lock: true" in ajax call you can use this function to check if interface is in lock state (it will be locked during server call and notification processing).
This check can be used to block some other interactions which do not result in ajaxcall or if you want to suppress errors. Note: normally you only need to use this.checkAction(...), this is for advanced cases.

It will also show error unless nomessage is set to true

function onChangeMyMind( evt ) {
if( this.checkLock() ) {
// Do the action
}
}

== Notifications ==

When something happens on the server side, your game interface Javascript logic received a notification.
If you have not done so yet check what notification are in [[Main_game_logic:_yourgamename.game.php#Notifications]]

Here's how you can handle these notifications on the client side.

=== Subscribe to notifications ===

'''dojo.subscribe(notif_type: string, callback_obj: Object, handler: string|handler)'''
* notif_type - notification type/name send by php server
* callback_obj - usually this
* handler - if string method of callback_obj with name name is called, when notification is called, with notification object as parameter (see below)

Your Javascript "setupNotifications" method is the place where you can subscribe to notifications from your PHP code.

Here's how you associate one of your Javascript method to a notification "playDisc" (from Reversi example):

<pre>
setupNotifications: function() {
...
dojo.subscribe('playDisc', this, "notif_playDisc");
},
</pre>

Note: the "playDisc" corresponds to the name of the notification you define it in your PHP code, in your "notifyAllPlayers" or "notifyPlayer" method.

Then, you have to define your "notif_playDisc" method:

<pre>
notif_playDisc: function(notif) {
// Remove current possible moves (makes the board more clear)
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );
this.addDiscOnBoard( notif.args.x, notif.args.y, notif.args.player_id );
},
</pre>

In a notification handler like our "notif_playDisc" method, you can access all notifications arguments with "notif.args".

Example:

PHP

<pre>
$this->notifyAllPlayers( "apples", clienttranslate('player takes ${count} apples'), [ "count" => 3 ] );
</pre>

JavaScript

<pre>
setupNotifications: function() {
dojo.subscribe( 'apples', this, 'notif_apples' );
},

notif_apples: function(notif) {
//You can access the "count" like this:
alert("count = " + notif.args.count);
}
</pre>

=== The notification Object received by client ===

When sending a notification on your PHP, the client side will receive an Object with the following attributes:

* type - type of the notification (as passed by php function)
* log - the log string passed from php notification
* args - This is the arguments that you passed on your notification method on php
* bIsTableMsg - is true when you use [[Main_game_logic:_yourgamename.game.php#NotifyAllPlayers|NotifyAllPlayers]] method (false otherwise)
* channelorig - information about table ID (formatted as : "/table/t[TABLE_NUMBER]")
* gamenameorig - name of the game
* move_id - ID of the move associated with the notification
* table_id - ID of the table (comes as string)
* time - UNIX GMT timestamp
* uid - unique identifier of the notification
* h - unknown

'' Note that those information were inferred from observation on console log. If an Admin can confirm/correct (and remove this line), you're welcome :)''

=== Ignoring notifications ===

Sometimes you need to ignore some notification on client side. You don't want them to be shown in game log and you don't want them to be handled.

The most common use case is when a player gets private information. They will receive a specific notification (such as "You received Ace of Heart"), while other players would receive more generic notification ("Player received a card").

In X.game.php
<pre>
$this->notifyAllPlayers("dealCard", clienttranslate('${player_name} received a card'), [
'player_id' => $playerId,
'player_name' => $this->getActivePlayerName()
]);

$this->notifyPlayer($playerId, "dealCardPrivate", clienttranslate('You received ${cardName}'), [
"type" => $card["type"],
"cardName" => $this->getCardName($card["type"])
]);
</pre>

The problem with this approach is that the active player will receive two notifications:
* Player1 received a card
* You received Ace of Hearts

Hence, notification ignoring.

NOTE: You can think that it would be possible to send such notification to all players except active just by using notifyPlayer and it seems to work. The problem however is that table spectators would miss such notification and their user interface (and game log) wouldn't be updated. Since there is no way to send notification just to spectators, ignoring the notification (or "filtering") is the only reasonable solution.

'''setIgnoreNotificationCheck(notif_type: string, predicate: ((notif: Notif)=>boolean))'''
This method will set a check whether any of notifications of specific type should be ignored.

The parameters are:
* notif_type: type of the notification
* predicate (notif => boolean): a function that will receive notif object and will return true if this specific notification should be ignored

Before dispatching any notification of this type, the framework will call predicate to check whether notification should be ignored, if it return true - the notification will be dispatched, i.e. logged or handled.

<pre>
this.notifqueue.setIgnoreNotificationCheck( 'dealCard', (notif) => (notif.args.player_id == this.player_id) );
</pre>

IMPORTANT: Remember that this notification is ignored on the client side, but was still received by the client. Therefore it shouldn't contain any private information as cheaters can get it. In other words this is not a way to hide information.

IMPORTANT: When a game is reloaded with F5 or when opening a turn based game, old notifications are replayed as history notification. They are used just to update the game log and are stripped of all arguments except player_id, i18n and any argument present in message. If you use and other argument in your predicate you should '''preserve''' it as explained [[Main_game_logic:_yourgamename.game.php#Notify_players|here]].

=== Synchronous notifications ===

When several notifications are received by your game interface, these notifications are processed immediately, one after the other, in the same exact order they have been generated in your PHP game logic.

However, sometimes, you need to give some time to the players to figure out what happened on the game before jumping to the next notification. Indeed, in many games, there are a lot of automatic actions, and the computer is going to resolve all these actions very fast if you don't tell it not to do so.

As an example, for Reversi, when someone is playing a disc, we want to wait 500 milliseconds before doing anything else in order the opponent player can figure out what move has been played.

Here's how we do this, right after our subscription:
<pre>
dojo.subscribe( 'playDisc', this, "notif_playDisc" );
this.notifqueue.setSynchronous( 'playDisc', 500 ); // Wait 500 milliseconds after executing the playDisc handler
</pre>

-----

It is also possible to control the delay timing dynamically (e.g., using notification args). As an example, maybe your notification 'cardPlayed' should pause for a different amount of time depending on the number or type of cards played.

For this case, use '''setSynchronous''' without specifying the duration and use '''setSynchronousDuration''' within the notification callback.

* NOTE: If you forget to invoke '''setSynchronousDuration''', the game will remain paused forever!

<pre>
setupNotifications: function () {
dojo.subscribe( 'cardPlayed', this, 'notif_cardPlayed' );
this.notifqueue.setSynchronous( 'cardPlayed' ); // wait time is dynamic
...
},

notif_cardPlayed: function (notif) {
// MUST call setSynchronousDuration

// Example 1: From notification args (PHP)
this.notifqueue.setSynchronousDuration(notif.args.duration);
...

// Or, example 2: Match the duration to a Dojo animation
var anim = dojo.fx.combine([
...
]);
anim.play();
this.notifqueue.setSynchronousDuration(anim.duration);
},
</pre>

You can also manually call this.notifqueue.setSynchronousDuration(0) once client operations are finished, but be careful that even fast replay still has a path to call it.

'''WARNING: combining synchronous and ignored notifications'''
You must be careful when combining dynamic synchronous durations (as described above) with ignored notifications. If you have a conditionally ignored notification like this (see below section):

<pre>this.notifqueue.setIgnoreNotificationCheck( 'myNotif', (notif) => (notif.args.player_id == this.player_id) /* or any other condition */ )</pre>

then you CANNOT do

<pre>this.notifqueue.setSynchronous('myNotif');</pre>

as, when the ignored check passes, the notification handler, in which `this.notifqueue.setSychronousDuration` is called, is never called and so the duration is never set and interface locking results.

The workaround is to set a "dummy" time:

<pre>this.notifqueue.setSynchronous('myNotif', 5000);</pre>

whose value is irrelevant but must be large enough to cover the time before the notification handler is called. The large value never actually comes into play because the notification is either ignored, or the synchronous duration is reset to a sensible value inside the handler.

=== Pre-defined notification types ===

'''tableWindow''' - This defines notification to display [[Game_interface_logic:_yourgamename.js#Scoring_dialogs|Scoring Dialogs]], see below.

'''message''' - This defines notification that shows on players log and have no other effect (technically any unhandled notification will do the same but its recommended to use this keyword for consistency)

// You can call this on php side without doing anything on client side
self::notifyAllPlayers( 'message', clienttranslate('hello'), [] );

'''simplePause''' - This notification will just delay other notifications, maybe useful if you know you need some extra time for animation or something. Requires a time parameter.

<pre>
self::notifyAllPlayers( 'simplePause', '', [ 'time' => 500] ); // time is in milliseconds
</pre>

Note: the following types are RESERVED by framework, do not use:

gameStateChange gameStateChangePrivateArg gameStateMultipleActiveUpdate newActivePlayer playerstatus yourturnack clockalert tableInfosChanged playerEliminated tableDecision archivewaitingdelay end_archivewaitingdelay replaywaitingdelay end_replaywaitingdelay replayinitialwaitingdelay end_replayinitialwaitingdelay aiPlayerWaitingDelay replay_has_ended updateSpectatorList wouldlikethink updateReflexionTime undoRestorePoint resetInterfaceWithAllDatas zombieModeFail zombieModeFailWarning aiError skipTurnOfPlayer zombieBack allPlayersAreZombie gameResultNeutralized playerConcedeGame showTutorial showCursor showCursorClick skipTurnOfPlayerWarning banFromTable resultsAvailable switchToTurnbased newPrivateState infomsg

== Tooltips ==

=== Adding static tooltips ===

'''this.addTooltip(nodeId: string, helpStringTranslated: string, actionStringTranslated: string, delay?: number): void'''

Add a simple text tooltip to the DOM node.

Specify 'helpStringTranslated' to display some information about "what is this game element?".
Specify 'actionStringTranslated' to display some information about "what happens when I click on this element?".

You must specify both of the strings. You can only use one and specify an empty string ('') for the other one.

When you pass text directly function _() must be used for the text to be marked for translation! Except for empty string.

Parameter "delay" is optional. It is primarily used to specify a zero delay for some game element when the tooltip gives really important information for the game - but remember: no essential information must be placed in tooltips as they won't be displayed in some browsers (see [[BGA_Studio_Guidelines|Guidelines]]).

Example:
<pre>
this.addTooltip( 'cardcount', _('Number of cards in hand'), '' );
</pre>

Note: this generates static tooltip and attaches to existing dom element, if you need to generate tooltip more dynamically you have to call that method every time information about object is updated or use completely different tehnique, see dynamic tooltips below.

'''this.addTooltipHtml(nodeId: string, html: string, delay?: number): void'''

Add an HTML tooltip to the DOM node (for more elaborate content such as presenting a bigger version of a card).

'''this.addTooltipToClass(cssClass: string, helpStringTranslated: string, actionStringTranslated: string, delay?: number ): void'''

Add a simple text tooltip to all the DOM nodes set with this cssClass. See more details above for this.addTooltip.
this.addTooltipToClass( 'meeple', _('This is A Meeple'), _('Click to tickle') );

IMPORTANT: all concerned nodes must exist and have IDs to get tooltips.

'''this.addTooltipHtmlToClass(cssClass: string, html: string, delay?: number): void'''

Add an HTML tooltip to to all the DOM nodes set with this cssClass (for more elaborate content such as presenting a bigger version of a card).

IMPORTANT: all concerned nodes must exist and have IDs to get tooltips.

=== Removing static tooltips ===

'''this.removeTooltip(nodeId: string): void'''

Remove a tooltip from the DOM node with given id.

=== Advanced tooltips ===

'''force tooltip to open'''

If you want to force tooltip to open in reaction to some other action, i.e. click you can do this

this.tooltips[id].open(id)

where id is the id of the tooltip node where tooltip was installed.

'''dynamic tooltips'''

See [[BGA_Studio_Cookbook#Dynamic_tooltips]]

'''tooltips on mobile'''

Tooltips is very unreliable on mobile, it is recommended to implement some other method to obtaining same information,
such as simple click handler in dedicated "Help" mode or provide dedicated clickable areas such as corner of card.

== Warning messages ==

Sometimes, there is something important that is happening in the game and you have to make sure all players get the message. Most of the time, the evolution of the game situation or the game log is enough, but sometimes you need something more visible.

Ex: someone fulfills one of the end of the game conditions, so this is the last turn.

'''this.showMessage(msg: string, type: string): void'''

showMessage shows a message in a big rectangular area on the top of the screen of the current player, and it dissapears after few seconds (also it will be in the log in some cases).

* "msg" is the string to display. It should be translated.
* "type" can be set to "info", "error", "only_to_log" or custom string. If set to "info", the message will be an informative message on a white background. If set to "error", the message will be an error message on a red background and it will be added to log. If set to "only_to_log", the message will be added to the game log but will not popup at the top of the screen.
If set to custom string, it will be transparent, to use custom type define "head_xxx" in css, where xxx is the type. For example if you want yellow warning, use "warning" as type and add this to css:
.head_warning {
background-color: #e6c66e;
}

Important: the normal way to inform players about the progression of the game is the game log. The "showMessage" is intrusive and should not be used often.

<pre>
notif_messageinfo: function(notif) {
if (!g_archive_mode) {
var message = this.format_string_recursive(notif.log, notif.args);
this.showMessage(_('Announcement:') + " " + message, 'info');
}
},
</pre>

Show message could be used on the client side to prevent user wrong moves before it is send to server.
Example from 'battleship':
<pre>
onGrid: function(event) {
if (checkIfPlayerTriesToFireOnThemselves(event)) {
this.showMessage(_('This is your own board silly!'), 'error');
return;
}
...
},
</pre>

'''this.showMoveUnauthorized(): void'''

Shows predefined user error that move is unauthorized now

<pre>
onPet: function(event) {
if (checkPet(event)==false) {
this.showMoveUnauthorized();
return;
}
...
},
</pre>

== Dialogs ==

=== Confirmation dialog ===

When an important action with a lot of consequences is triggered by the player, you may want to propose a confirmation dialog.

CAREFUL: the general guideline of BGA is to AVOID the use of confirmation dialogs. Confirmation dialogs slow down the game and bother players. The players know that they have to pay attention to each move when they are playing online.

The situations where you should use a confirmation dialog are the following:
* It must not happen very often during a game.
* It must be linked to an action that can really "kill a game" if the player does not pay attention.
* It must be something that can be done by mistake (ex: a link on the action status bar).

'''this.confirmationDialog(message: string, yesHandler: (param: any) => void, noHandler?: (param: any) => void, param?: any): void'''

* message - message will be shown to user, use _() to translate
* yesHandler - non-optional handler to be called on yes
* noHandler - optional handler to called on no
* param - if specified, it will be passed to both handlers
NOTE: this is async function, it does not return anything and you should not do anything after, you must do everything in handlers

How to display a confirmation dialog:
<pre>
this.confirmationDialog(_("Are you sure you want to bake a pie?"), () => {
this.bakeThePie();
});
return; // nothing should be called or done after calling this, all action must be done in the handler
</pre>
With param and both handlers
<pre>
this.confirmationDialog(_("Are you sure you want to bake a pie?"),
(ingredient) => this.bakeThePie(ingredient),
(ingredient) => console.log(`cancelled baking of ${ingredient}`),
'apple');
</pre>

=== Multiple choice dialog ===

You can use this dialog to give user a choice with small amount of options

'''this.multipleChoiceDialog(message: string, choices: string[], callback: (choice: number) => void): void'''
* message - message will be shown to user, use _() to translate
* choices - array of choices
* callback - non-optional handler to be called on choice made, the choice parameter is the INDEX of the choice from the array of choices

NOTE: this is async function, it does not return anything and you should not do anything after, you must do everything in handlers
NOTE: there is no cancel handler, so make sure you gave user a choice to get out of it

Example:
<pre>
const keys = ["0", "1", "5", "10"];
this.multipleChoiceDialog(_("How many bugs to fix?"), keys, (choice) => {
if (choice==0) return; // cancel operation, do not call server action
var bugchoice = keys[choice]; // choice will be 0,1,2,3 here
this.bgaPerformAction("fixBugs", { number: bugchoice });
});
return; // must return here
</pre>

=== Generic Dialogs ===

As a general rule, you shouldn't use dialogs windows.

BGA guidelines specify that all game elements should be displayed on the main screen. Players can eventually scroll down to see game elements they don't need to see anytime, and you may eventually create anchors to move between game area section. Of course dialogs windows are very practical, but the thing is: all players know how to scroll down, and not all players know how to show up your dialog window. In addition, when the dialog shows up, players can't access the other game components.

Sometimes although, you need to display a dialog window. Here is how you do this:

// Create the new dialog over the play zone. You should store the handler in a member variable to access it later
this.myDlg = new ebg.popindialog();
this.myDlg.create( 'myDialogUniqueId' );
this.myDlg.setTitle( _("my dialog title to translate") );
this.myDlg.setMaxWidth( 500 ); // Optional

// Create the HTML of my dialog.
// The best practice here is to use [[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl#Javascript_templates|Javascript templates]]
var html = this.format_block( 'jstpl_myDialogTemplate', {
arg1: myArg1,
arg2: myArg2,
...
} );

// Show the dialog
this.myDlg.setContent( html ); // Must be set before calling show() so that the size of the content is defined before positioning the dialog
this.myDlg.show();

// Now that the dialog has been displayed, you can connect your method to some dialog elements
// Example, if you have an "OK" button in the HTML of your dialog:
dojo.connect($('my_ok_button'), 'onclick', this, (event) => {
event.preventDefault();
this.myDlg.destroy();
});

If necessary, you can remove the default top right corner 'close' icon, or replace the function called when it is clicked:
// Removes the default close icon
this.myDlg.hideCloseIcon();

// Replace the function call when it's clicked
this.myDlg.replaceCloseCallback((event) => { ... });

=== Scoring dialogs ===

Sometimes at the end of a round you want to display a big table that details the points wins in each section of the game.

Example: in Hearts game, we display at the end of each round the number of "heart" cards collected by each player, the player who collected the Queen of Spades, and the total number of points loose by each player.

Scoring dialogs are managed entirely on '''PHP side''', but they are described here as their effects are visible only on client side.

Displaying a scoring dialog is quite simple and is using a special notification type: "tableWindow":
<pre>
// on PHP side:
$this->notifyAllPlayers( "tableWindow", '', array(
"id" => 'finalScoring',
"title" => clienttranslate("Title of the scoring dialog"),
"table" => $table
));
</pre>

The "table" argument is a 2 dimensional PHP array that describes the table you want to display, line by line and column by column.

Example: display an 3x3 array of strings
<pre>
$table = [
[ "one", "two", "three" ], // This is my first line
[ "four", "five", "six" ], // This is my second line
[ "seven", "height", "nine" ] // This is my third line
];
</pre>

As you can see above, in each "cell" of your array you can display a simple string value. But you can also display a complex value with a template and associated arguments like this:
<pre>
$table = [
[ "one", "two", [ "str" => clienttranslate("a string with an ${argument}"), "args" => [ 'argument' => 'argument_value' ] ] ],
[ "four", "five", "six" ],
[ "seven", "height", "nine" ]
];
</pre>

This is especially useful when you want to display player names with colors. Example from "Hearts":
<pre>
$firstRow = [ '' ];
foreach( $players as $player_id => $player ) {
$cell = [ 'str' => '${player_name}',
'args' => [ 'player_name' => $player['player_name'] ],
'type' => 'header'
];
$firstRow[] = $cell;
}
$table[] = $firstRow;
...
</pre>

You can also use three extra attributes in the parameter array for the notification:
* '''header''': the content for this parameter displays before the table (also, the html will be parsed and player names will be colored according to the current game colors).
* '''footer''': the content for this parameter displays after the table (no parsing for coloring the player names)
* '''closing''': if this parameter is used, a button will be displayed with this label at the bottom of the popup and will allow players to close it (more easily than by clicking the top right 'cross' icon).

<pre>
$this->notifyAllPlayers( "tableWindow", '', [
"id" => 'finalScoring',
"title" => clienttranslate("Title of the scoring dialog"),
"table" => $table,
"header" => ['str' => clienttranslate('Table header with parameter ${number}'),
'args' => [ 'number' => 3 ],
],
"footer" => '<div class="myfoot"></div>',
"closing" => clienttranslate( "Closing button label" )
] );
</pre>

Note: currently id is not used - so you cannot access resulting div by id on js side
Note: any traslatable stirng have to be wrapped by clienttranslate() on top level OR it has to be recursive template.

DO NOT DO THIS:
<pre>
"footer" => '<div>'.clienttranslate( "The end" ).'</div>', // this will not work for translations!!!
</pre>

=== Scoring animated display ===

Sometimes, you may want to display a score value over an element to make the scoring easier to follow for the players (Terra Mystica final scoring for example).
You can do it with:

'''this.displayScoring(anchor_id: string, color: string, score: number | string, duration?: number, offset_x?: number, offset_y?: number): void'''

'''anchor_id''': ID of the html element to place the animated score onto (without the '#')

'''color''': hexadecimal RGB representation of the color (should be the color of the scoring player), but without a leading '#'. For instance, 'ff0000' for red.

'''score''': numeric score to display, prefixed by a '+' or '-'

'''duration''': animation duration in milliseconds (optional, default is 1000)

'''offset_x''' and '''offset_y''': if both offset_x and offset_y are defined and not null, apply the following offset (in pixels) to the scoring animation.
Note that the score is centered in the anchor, so the offsets might have to be negative if you calculate the position.

Note: if you want to display successively each score, you can use ''this.notifqueue.setSynchronous()'' function.
<pre>
setupNotifications: function() {
dojo.subscribe( 'displayScoring', this, "notif_displayScoring" );
...
}
...

notif_displayScoring: function(notif) {
const duration = notif.args.duration?notif.args.duration:1000;
this.notifqueue.setSynchronous('displayScoring', duration );
this.displayScoring( notif.args.target, notif.args.color, notif.args.score, duration);
},
</pre>

=== Speech bubble ===

For better interactivity in some games (Love Letter for example), you may use comic book style speech bubbles to express the players voices.
This is done with showBubble:

'''this.showBubble(anchor_id: string, text: string, delay?: number, duration?: number, custom_class?: string): void'''

* anchor_id - where to attach the bubble
* text - what to put in bubble, can be html
* delay - delay in milliseconds (optional, default 0)
* duration - duration of animation in milliseconds (optional, default 3000)
* custom_class - extra class to add to bubble (optional), if you need to override the default bubble style

<pre>
this.showBubble('meeple_2', _('Hello'), 0, 1000, 'pink_bubble');
</pre>

<pre>
notif_speechBubble(notif) {
var html = this.format_string_recursive(notif.args.text, notif.args.args);
this.showBubble(notif.args.target, html, notif.args.delay ?? 0, notif.args.duration ?? 1000);
},
</pre>

'''Warning''': if your bubble could overlap other active elements of the interface (buttons in particular), as it stays in place even after disappearing, you should use a custom class to give it the style "pointer-events: none;" in order to intercept click events.

Note: If you want this visually, but want to take complete control over this bubble and its animation (for example to make it permanent) you can just use div with 'discussion_bubble' class on it, and content of div is what will be shown.

== Translations ==

See [[Translations]]

== Players panels ==

=== Update players score ===

The column player_score from the player table is automatically loaded into this.scoreCtrl and therefore into the stars location on the player board. This occurs sometime after the game setup() function. However this score must be updated as the game progresses using notifications.

Note: this.scoreCtrl[player_id] is object of class [[Counter]], you can use other counter API.

Increase a player score (with a positive or negative number):

<pre>
this.scoreCtrl[ player_id ].incValue( score_delta );
</pre>

Set a player score to a specific value:

<pre>
this.scoreCtrl[ player_id ].setValue( new_score );
</pre>

Set a player score to a specific value with animation:

<pre>
this.scoreCtrl[ player_id ].toValue( new_score );
</pre>

Typical usage would be (that will process 'score' notification):
<pre>
setupNotifications : function() {
...
dojo.subscribe('score', this, "notif_score");
},
notif_score: function(notif) {
this.scoreCtrl[notif.args.player_id].setValue(notif.args.player_score);
},
</pre>

=== Adding stuff to player's panel ===

At first, create a new "JS template" string in your template (tpl) file:

(from Gomoku example)
<pre>
var jstpl_player_board = '\<div class="cp_board">\
<div id="stoneicon_p${id}" class="gmk_stoneicon gmk_stoneicon_${color}"></div><span id="stonecount_p${id}">0</span>\
</div>';
</pre>

Then, you add this piece of code in your JS file to add this template to each player panel:

<pre>
// Setting up player boards
for( var player_id in gamedatas.players )
{
var player = gamedatas.players[player_id];

// Setting up players boards if needed
var player_board_div = $('player_board_'+player_id);
dojo.place( this.format_block('jstpl_player_board', player ), player_board_div );
}
</pre>

(Note: the code above is of course from your "setup" function in your Javascript).

Very often, you have to distinguish current player and others players. In this case, you just have to create another JS template (ex: jstpl_otherplayer_board) and use it when "player_id" is different than "this.player_id".

=== Fixing Player Panel heights ===

You may find that the player panels don't automatically resize when adding something to (or removing something from) a player panel while the display is in portrait mode (i.e. the player summary panels are at the top of the screen rather than down the right side).

When this happens, call <pre>this.adaptPlayersPanels();</pre> This recalculates the layout and also adjusts the position of the actionbar for you.

=== Player's panel disabling/enabling ===

'''this.disablePlayerPanel(player_id: number): void'''

Disable given player panel (the panel background become gray).

Usually, this is used to signal that this played passes, or will be inactive during a while.

Note that the only effect of this is visual. There are no consequences on the behaviour of the panel itself.

'''this.enablePlayerPanel(player_id:number): void'''

Enable a player panel that has been disabled before.

'''this.enableAllPlayerPanels(): void'''

Enable all player panels that has been disabled before.

=== Player order ===

'''this.updatePlayerOrdering(): void'''

This function makes sure that player order in player's panel matches this.gamedatas.playerorder and its normally called by framework.
You can call it yoursel if you change this.gamedatas.playerorder from notification.
Also you can override this function to change defaults OR insert a non-player panel [[BGA_Studio_Cookbook#Inserting_non-player_panel]].

=== Counters ===
Note: there is bga component called "ebg/counter" this API is not using it, these methods
below declared right in core game. If you need animation for counters use ebg/counter

To use this API just create a counter dom element like this (class does not really matter)
<pre>
<div class="counter" id="bread"></div>
<div class="counter" id="coin"></div>
</pre>
The "bread" will the counter name.

The php code should send all "counters" data from getAllDatas() method like this

game.php
<pre>
protected function getAllDatas() {
// (the key must match counter_name)
$result['counters']=[
'bread' => [
'counter_name' => 'bread',
'counter_value' => 3
],
'coin' => [
'counter_name' => 'coin',
'counter_value' => 5
]
];
return $result;
}
</pre>

'''setCounter(counter_name: stirng, new_value: string | number): void'''

updates the global this.gamedatas.counters and value of node $(counter_name)
<pre>
notif_counter: function(notif) {
this.setCounter(notif.args.counter_name, notif.args.counter_value);
},
</pre>

'''incCounter(counter_name: string, delta: number): void'''
<pre>
notif_counter : function(notif) {
this.incCounter(notif.args.counter_name, notif.args.inc);
},
</pre>

'''updateCounters(counters: object): void'''

Useful for updating game counters in the player panel (such as resources).
'counters' arg is map of counters (the key must match counter_name)
{
'bread': {
'counter_name' : 'bread',
'counter_value' => 3
},
'coin': {
'counter_name' : 'coin',
'counter_value' => 5
}
}
All counters MUST be referenced in this.gamedatas.counters (means they should be send from php) and will be updated.
DOM objects referenced by 'counter_name' will have their innerHTML updated with 'counter_value'.

Usually you call this from notification

<pre>
notif_counter : function(notif) {
this.updateCounters(notif.args.counters);
},
</pre>

== BGA GUI components ==

BGA framework provides some useful ready-to-use components for the game interface:

[[Studio#BGA_Studio_game_components_reference]]

Note that each time you are using an additional component, you must declare it at the top of your Javascript file in the list of modules used.

Example if you are using "ebg.stock":
<pre>
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/stock" /// <=== we are using ebg.stock module
],
</pre>

== BGA Buttons ==

=== Basic Button ===

'''this.addActionButton(id: string, label: string, method: string | eventhandler, destination?: string, blinking?: boolean, color?: string): void'''

You can use this method to add an action button in the main action status bar (or other places).

Arguments:
* id: an element ID that should be unique in your HTML DOM document.
* label: the text of the button. Should be translatable (use _() function). Note: this can also be any html, such as "<div class='brick'></div>", see example below on how to make image action buttons.
* method: the name of your method that must be triggered when the player clicks on this button (can be name of the method on game class or handler).
* destination (optional): id of parent on where to add button, ONLY use in rare cases if location is not action bar. Use '''null''' as value if you need to specify other arguments.
* blinking (optional): if set to '''true''', the button is going blink to catch player's attention. Please DO NOT abuse blinking button. If you need button to blink after some time passed add class 'blinking' to the button later.
* color: could be '''blue''' (default), '''red''','''gray''' or '''none'''.

You should only use this method in your "onUpdateActionButtons" method. Usually, you use it like this:

<pre>
onUpdateActionButtons: function( stateName, args ) {
if (this.isCurrentPlayerActive()) {
switch( stateName ) {
case 'giveCards':
this.addActionButton( 'giveCards_button', _('Give selected cards'), 'onGiveCards' );
this.addActionButton( 'pass_button', _('Pass'), () => this.bgaPerformAction('actPass') );
break;
}
}
},
</pre>

In the example above, we are adding a "Give selected cards" button in the case we are on game state "giveCards". When player clicks on this button, it triggers our "onGiveCards" method.

Example using blinking red button:
<pre>
this.addActionButton( 'button_confirm', _('Confirm?'), 'onConfirm', null, true, 'red');
</pre>

If you want to call the handler with arguments, you can use arrow functions, like this:
<pre>
this.addActionButton( 'commit_button', _('Confirm'), () => this.onConfirm(this.selectedCardId), null, false, 'red');
</pre>

=== Image Button ===

You can use the same method, but add extra class to a button to disable the padding and style it, i.e.
<pre>
this.addActionButton( 'button_brick', '<div class="brick"></div>', ()=>{... on brick ...}, null, null, 'gray');
dojo.addClass('button_brick','bgaimagebutton');
</pre>

where

<pre>
.bgaimagebutton {
padding: 0px 12px;
min-height: 28px;
border: none;
}
</pre>

If you use this a lot, you can define a helper function, i.e.
<pre>
/**
* This method can be used instead of addActionButton, to add a button which is an image (i.e. resource). Can be useful when player
* need to make a choice of resources or tokens.
*/
addImageActionButton: function(id, div, handler, bcolor, tooltip) {
if (typeof bcolor == "undefined") {
bcolor = "gray";
}
// this will actually make a transparent button id color = gray
this.addActionButton(id, div, handler, null, false, bcolor);
// remove border, for images it better without
dojo.style(id, "border", "none");
// but add shadow style (box-shadow, see css)
dojo.addClass(id, "shadow bgaimagebutton");
// you can also add additional styles, such as background
if (tooltip) {
dojo.attr(id, "title", tooltip);
}
return $(id);
},
</pre>

=== Disabling Button ===

You can disable the '''bgabutton''' by adding the css class '''disabled''' in you js. The disabled button is still visible but is grey and not clickable.
For example in the '''onUpdateActionButtons''' :
<pre>
this.addActionButton('play_button_id', _('Play 1 to 3 cards'), 'playFunctionButton');
if (condition) {
dojo.addClass('play_button_id', 'disabled');
}
</pre>

=== Custom Buttons ===

You can create a custom button, but the BGA framework provides a standard button that requires only .css classes: '''bgabutton''' and '''bgabutton_${color}'''.

'''Examples:'''

<pre>
<a href="#" id="my_button_id" class="bgabutton bgabutton_blue"><span>My blue button</span></a>

<a href="#" id="my_button_id" class="bgabutton bgabutton_red bgabutton_big"><span>My big red button</span></a>
</pre>

'''Note''': To see it in action, check out ''Coloretto''.

=== Button outside of action bar ===

Use addActionButton() method with destination argument set
<pre>
this.addActionButton( 'commit_button', _('Confirm'), 'onConfirm', 'player_board', true, 'red');
</pre>

in example above the button will be place on object with id 'player_board'

== Image loading ==

See also [[Game_art:_img_directory]].

'''Be careful''': by default, ALL images of your img directory are loaded on a player's browser when he loads the game. For this reason, don't let in your img directory images that are not useful, otherwise it's going to slowdown the game load.

'''this.dontPreloadImage(image_file_name: string)'''

Using dontPreloadImage, you tell the interface to not preload a specific image in your img directory.

Example of use:
<pre>
this.dontPreloadImage( 'cards.png' );
</pre>

This is particularly useful if for example you have 2 different themes for a game. To accelerate the loading of the game, you can specify to not preload images corresponding to the other theme.

Another example of use: in "Gosu" game with Kamakor extension, you play with 5 sets of cards among 10 available. Cards images are organized by sets, and we only preload the images corresponding to the 5 current sets with '''ensureSpecificGameImageLoading( image_file_names_array )'''.
<pre>
// By default, do not preload anything
this.dontPreloadImage( 'cards.png' );
this.dontPreloadImage( 'clan1.png' );
this.dontPreloadImage( 'clan2.png' );
this.dontPreloadImage( 'clan3.png' );
this.dontPreloadImage( 'clan4.png' );
this.dontPreloadImage( 'clan5.png' );
this.dontPreloadImage( 'clan6.png' );
this.dontPreloadImage( 'clan7.png' );
this.dontPreloadImage( 'clan8.png' );
this.dontPreloadImage( 'clan9.png' );
this.dontPreloadImage( 'clan10.png' );
var to_preload = [];
for( i in this.gamedatas.clans )
{
var clan_id = this.gamedatas.clans[i];
to_preload.push( 'clan'+clan_id+'.png' );
}

this.ensureSpecificGameImageLoading( to_preload );

</pre>

'''Note:''' You don't need to specify to not preload game box images (game_box.png, game_box75.png...) since they are not preloaded by default.

'''this.ensureSpecificGameImageLoading(list: string[])'''

This is oppostive of dontPreloadImage - its ensure specific images is loaded. Note: only makes sense if preload list is empty, otherwise everything is loaded anyway

'''load specific images'''
All images that will be preloaded stored in g_img_preload. If you want to override it directly - there is no API, but you can do this in GAME constructor

g_img_preload = ['tokens.png', 'trains.png', 'loc_plan.png', 'eng.png', 'eng-back.png'];

You can also set it to empty array and call ensureSpecificGameImageLoading() on specific images

== Sounds ==

Add a custom sound and make it load with your interface:

Add this in your template (.tpl) file:
<pre>
<audio id="audiosrc_<gamename>_<yoursoundname>" src="{GAMETHEMEURL}img/<gamename>_<yoursoundname>.mp3" preload="none" autobuffer></audio>
<audio id="audiosrc_o_<gamename>_<yoursoundname>" src="{GAMETHEMEURL}img/<gamename>_<yoursoundname>.ogg" preload="none" autobuffer></audio>
</pre>

Note: this is a requirement to provide both a mp3 and a ogg file with the names <code><gamename>_<yoursoundname>[.ogg][.mp3]</code>.

Play the sound (from your .js file):

<pre>
playSound('<gamename>_<yoursoundname>'); // do not add 'this.' - its a global function
</pre>

Disable the standard "move" sound for this move (to replace it with your custom sound):

Add this to your notification handler:

<pre>
this.disableNextMoveSound();
</pre>

Note: it only disable the sound for the next move.

== Title bar and states ==

=== Client states ===

Client states is a way to simulate the state transition but without actually going
to server. It is usefull when you need to ask user multiple questions before you
send things to server

'''this.setClientState(newState: string, args: object)'''

Example:
this.setClientState("client_playerPicksLocation", {
descriptionmyturn : _("${you} must select location"),
});

For more information see [[BGA_Studio_Cookbook#Multi_Step_Interactions:_Select_Worker.2FPlace_Worker_-_Using_Client_States]]

'''this.restoreServerGameState()'''
If you are in client state it will restore the current server state (cheap undo)

'''this.on_client_state'''
Boolean indicating that we are in client state

=== Title bar ===
If you simply want to show something in title bar you can do it directly
$('pagemaintitletext').innerHTML = text;

This however will not work with parameters and will not draw You in color,
if you want to do proper args rendering use method below

;'''this.removeActionButtons()'''
Removes all buttons from title bar

;'''this.updatePageTitle()'''
:This function allows to update the current page title and turn description according to the game state arguments. If the current game state description this.gamedatas.gamestate.descriptionmyturn is modified before calling this function it allows to update the turn description without changing state. This will handle arguments substitutions properly.

Note: this functional also will calls this.onUpdateActionButtons, if you want different buttons then state defaults, use method in example to replace them, if it becomes too clumsy use client states (see above)

Example from Terra Mystica:
<pre>
onClickFavorTile: function( evt ) {
...
if ( ... ) {
this.gamedatas.gamestate.descriptionmyturn = _('Special action: ') + _('Advance 1 space on a Cult track');
this.updatePageTitle();
this.removeActionButtons();
this.addActionButton( ... );
...
return;
}
...

}
</pre>

== User preferences ==
'''this.getGameUserPreference(pref_id)'''

Return the value of a user preference. It will return the value currently selected in the select combo box, in the top-right menu.

'''this.setGameUserPreference(pref_id, value)'''

Programmatically change a user preference. It will have the same effect as if the player changed the value in the select combo box, in the top-right menu.

'''this.onGameUserPreferenceChanged'''

A callback you can define if you want to be notified when a user changes a user preference.

Example:<pre>
onGameUserPreferenceChanged: function(pref_id, pref_value) {
switch (pref_id) {
case 201:
document.getElementsByTagName('html')[0].classList.toggle('dark-background', pref_value == 2);
break;
}
}
</pre>

== Other useful stuff ==

'''dojo.hitch'''

With dojo.hitch, you can create a callback function that will run with your game object context whatever happen.

Typical example: display a BGA confirmation dialog with a callback function created with dojo.hitch:

<pre>
this.confirmationDialog( _('Are you sure you want to make this?'), dojo.hitch( this, function() {
this.bgaPerformAction('makeThis');
} ) );
</pre>

In the example above, using dojo.hitch, we ensure that the "this" object will be set when the callback is called.

NOTE: In modern JS there are lambdas that eliminate need for that, the example above will look like this
<pre>
this.confirmationDialog( _('Are you sure you want to make this?'), () => this.bgaPerformAction( 'makeThis') );
</pre>

;'''onScreenWidthChange()'''
:This function can be overridden in your game to manage some resizing on the client side when the browser window is resized. This function is also triggered at load time, so it can be used to adapt to the :viewport size at the start of the game too.

; this.bRealtime
: Return true if the game is in realtime. Note that having a distinct behavior in realtime and turn-based should be exceptional.

; g_replayFrom
: Global contains replay number in live game, it is set to undefined (i.e. not set) when it is not a replay mode, so consequentially the good check is '''typeof g_replayFrom != 'undefined'''' which returns true if the game is in replay mode <i>during the game</i> (the game is ongoing but the user clicked "replay from this move" in the log)

; g_archive_mode
: Returns true if the game is in archive mode <i>after the game</i> (the game has ended)

; this.instantaneousMode
: Returns true during replay/archive mode if animations should be skipped. Only needed if you are doing custom animations. (The BGA-provided animation functions like <i>this.slideToObject()</i> automatically handle instantaneous mode.)
: Technically, when you click "replay from move #20", the system replays the game from the very beginning with moves 0 - 19 happening in instantaneous mode and moves 20+ happening in normal mode.

; g_tutorialwritten
: Returns an object like the below if the game is in tutorial mode, or undefined otherwise. Tutorial mode is a special case of archive mode where comments have been added to a previous game to teach new players the rules.
{
author: "91577332",
id: "576",
mode: "view"
status: "alpha"
version_override: null
viewer_id: "84554161"
}

'''getBgaEnvironment(): string'''
: Returns "studio" for studio and "prod" for production environment (i.e. where games current runs). Only useful for debbugging hooks.
Note: alpha server is also "prod"

[[Category:Studio]]

Game interface logic: Game.js

2024-09-25T16:45:37Z

Sguzzer Gunayer: /* Creating and Destroying elements */

{{Studio_Framework_Navigation}}

__TOC__

This is the main file for your game interface. Here you will define:

* Which actions on the page will generate calls to the server.
* What happens when you get a notification for a change from the server and how it will show in the browser.
* Setup user interface

== File structure ==

The details of how the file is structured are described below with comments in the code skeleton provided to you.

Here is the basic structure:

* '''constructor''': here you can define global variables for your whole interface.
* '''setup''': this method is called when the page is refreshed, and sets up the game interface.
* '''onEnteringState''': this method is called when entering a new game state. You can use it to customize the view for each game state.
* '''onLeavingState''': this method is called when leaving a game state.
* '''onUpdateActionButtons''': called on state changes, in order to add action buttons to the status bar. Note: in a multipleactiveplayer state, it will be called when another player has become inactive.
* ''(utility methods)'': this is where you can define your utility methods.
* ''(player's actions)'': this is where you can write your handlers for player actions on the interface (example: click on an item).
* '''setupNotifications''': this method associates notifications with notification handlers. For each game notification, you can trigger a javascript method to handle it and update the game interface.
* ''(notification handlers)'': this is where you define the notifications handlers associated with notifications in '''setupNotifications''', above.

More details:

'''setup(gamedatas: object) '''
This method must set up the game user interface according to current game situation specified in parameters.
The method is called each time the game interface is displayed to a player, ie:

* when the game starts
* when a player opens a game in the browser later
* when a player refreshes the game page (F5)
* when player does a server side Undo

"gamedatas" argument contains all data retrieved by your "getAllDatas" PHP method and some more.

'''onEnteringState(stateName: string, args: { args: any } | null): void'''

This method is called each time we enter a new game state.
You can use this method to perform some user interface changes at this moment.
To access state arguments passed via calling php arg* method use args?.args.
Typically you would do something only for active player, using this.isCurrentPlayerActive() check.
It is also called (for the current game state only) when doing a browser refresh (after the setup method is called).

'''Warning''': for multipleactiveplayer states:
the active players are NOT active yet so you must use onUpdateActionButtons to perform the client side operation which depends on a player active/inactive status.
If you are doing initialization of some structures which do not depend on the active player, you can just replace (this.isCurrentPlayerActive()) with (!this.isSpectator)
for the main switch in that method.

See more details in [[Your_game_state_machine:_states.inc.php#Difference_between_Single_active_and_Multi_active_states]]

'''onLeavingState(stateName: string): void'''

This method is called each time we leave a game state.
You can use this method to perform some user interface changes at this point (i.e. cleanup).

'''onUpdateActionButtons(stateName: string, args: object | null): void'''

In this method you can manage "action buttons" that are displayed in the action status bar and highlight active UI elements.
To access state arguments passed via calling php arg* method use '''args''' parameter. Note: args can be null! For '''game''' states and when you don't supply state args function - it is null.
This method is called when the active or multiactive player changes. In a classic "activePlayer" state this method is called before the onEnteringState state.
In multipleactiveplayer state it is a mess. The sequencing of calls depends on whether you get into that state from transitions OR from reloading the whole game (i.e. F5).

See more details in [[Your_game_state_machine:_states.inc.php#Difference_between_Single_active_and_Multi_active_states]]

== Dojo framework ==

BGA uses the [http://dojotoolkit.org/ Dojo Javascript framework].

The Dojo framework allows us to do complex things more easily. The BGA framework uses Dojo extensively.

To implement a game, you only need to use a few parts of the Dojo framework. All the Dojo methods you need are described on this page.

== Javascript minimization (after July 2020) ==

For performance reasons, when deploying a game the javascript code is minimized using '''terser''' (https://github.com/terser/terser). This minifier works with modern javascript syntax. From your project "Manage game" page, you can now test a minified version of your javascript on the studio (and revert to the original).

NB: it has been reported that there is an issue with this minifier and percentage values for opacity.

== Accessing Players Information ==

'''this.player_id: number'''
id of the player who is looking at the game. The player may not be part of the game (i.e. spectator)
if (notif.args.player_id == this.player_id) {
...
}

'''this.isSpectator: boolean'''
Flag set to true if the user at the table is a spectator (not a player).

Example:
<pre>
if (this.isSpectator) {
this.player_color = 'ffffff';
} else {
this.player_color = gamedatas.players[this.player_id].color;
}
</pre>

Note: If you want to hide an element from spectators, you should use [[Game_interface_stylesheet:_yourgamename.css#spectatorMode|CSS 'spectatorMode' class]].

You may consider making a function like this, to detect if the game is in a read-only state (i.e. non-interactive):
// Returns true for spectators, instant replay (during game), archive mode (after game end)
isReadOnly: function () {
return this.isSpectator || typeof g_replayFrom != 'undefined' || g_archive_mode;
}

'''this.gamedatas: object'''
Contains the initial set of data to init the game, created at game start or by game refresh (F5).
You can update it as needed to keep an up-to-date reference of the game on the client side if you need it, however most of the time this is unnecessary.

Note: In hotseat mode, the framework does not keep this.gamedatas of hotseat players and shares the same set as the main player to store data.

Note: be careful when you update this data structurally, many framework functions expect data to be certain way and they will break if they see something else.

Typical example of accessing player's info
<pre>
for (var player_id in this.gamedatas.players) {
var playerInfo = this.gamedatas.players [player_id];
var c = playerInfo.color;
var name = playerInfo.name;
// do something
}
</pre>

'''this.isCurrentPlayerActive(): boolean'''
Returns true if the player on whose browser the code is running is currently active (it's his turn to play). Note: see remarks above about usage of this function inside onEnteringState method.
if (this.isCurrentPlayerActive()) ...

'''this.getActivePlayerId(): number'''
Return the ID of the active player, or null if we are not in an "activeplayer" type state.
if (this.player_id == this.getActivePlayerId()) ...

'''this.getActivePlayers(): number[]'''
Return an array with the IDs of players who are currently active (or an empty array if there are none).

== Accessing and manipulating the DOM ==

=== Element by Id ===

'''$(elementId: ElementOrId)'''

The $ function is used to get an HTML element using its "id" attribute.

Example: modify the content of a "span" element:

<pre>
In your HTML code:
<span id="a_value_in_the_game_interface">1234</span>

In your Javascript code:
$('a_value_in_the_game_interface').innerHTML = "9999";
</pre>

Note: It is safe to use if you don't know if variable is string (id of element) or element itself, i.e.
<pre>
foo: function(card) {
card = $(card); // now its node, no need to write if (typeof card === 'string') ...
// but its good idea to check for null here
...
}
</pre>

'''getElementById(elementId: string)'''

Note: $() is the standard method to access some HTML element with the BGA Framework. You can use '''getElementById''' but it is longer to type and less handy as it does not do some checks.

=== Style ===

'''dojo.style(node: ElementOrId, styleName: string, styleValue: any): void'''

With dojo.style you can modify the CSS property of any HTML element in your interface.

Examples:

<pre>
// Make an element disappear
dojo.style( 'my_element', 'display', 'none' );

// Give an element a 2px border
dojo.style( 'my_element', 'borderWidth', '2px' );

// Change the background position of an element
// (very practical when you are using CSS sprites to transform an element to another)
dojo.style( 'my_element', 'backgroundPosition', '-20px -50px' );
</pre>

Note: if you have to modify several CSS properties of an element, or if you have a complex CSS transformation to do, you should consider using dojo.addClass/dojo.removeClass (see below).

You can also use object to set multiple values
<pre>
dojo.setStyle("thinger", {
"opacity": 0.5,
"border": "3px solid black",
"height": "300px"
});
</pre>

'''this.addStyleToClass(cssClassName: string, styleName: string, styleValue: any):''' '''void'''

Same as dojo.style(), but for all the nodes set with the specified cssClassName
Equivalent of

dojo.query(`.${aclass}`).style(styleName, styleValue)

<pre>
dojo.query("#baz > div").style({
opacity:0.75,
fontSize:"13pt"
});
</pre>

'''Vanilla JS style'''
$('my_element').style.display='none'; // set
var display = $('my_element').style.display; // get
$('my_element').style.removeProperty('display'); // remove

=== Classes ===

'''dojo.addClass(node: ElementOrId, classes: string): void'''

'''dojo.removeClass(node: ElementOrId, classes: string): void'''

'''dojo.hasClass(node: ElementOrId, aclass: string): void'''

'''dojo.toggleClass(node: ElementOrId, aclass: string): void'''

In many situations, many small CSS property updates can be replaced by a CSS class change (i.e., you add a CSS class to your element instead of applying all modifications manually).

Advantages are:
* All your CSS stuff remains in your CSS file.
* You can add/remove a list of CSS modifications with a simple function and without error.
* You can test whether you applied the CSS to an element with the '''dojo.hasClass''' method.

Example from ''Reversi'':

<pre>
// We add "possibleMove" to an element
dojo.addClass( 'square_'+x+'_'+y, 'possibleMove' );

// In our CSS file, the class is defined as:
.possibleMove {
background-color: white;
opacity: 0.2;
filter:alpha(opacity=20); /* For IE8 and earlier */
cursor: pointer;
}

// So we've applied 4 CSS property changes in one line of code.

// ... and when we need to check if a square is a possible move on the client side:
if( dojo.hasClass( 'square_'+x+'_'+y, 'possibleMove' ) )
{ ... }

// ... and if we want to remove all possible moves in one line of code (see "dojo.query" method):
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );
</pre>

'''Vanilla JS classList'''

This is the only exception where dojo versions are better
// add class
$(token_id).classList.addClass('possibleMove');
// remove class
$(token_id).classList.removeClass('possibleMove');
// add 2 classes
const myclasses = ['a','b'];
$(token_id).classList.addClass(...myclasses);
// add classes to query result
document.querySelectorAll(".hand .card").forEach((node)=>node.classList.addClass('possibleMove'));

=== Attributes ===

;dojo.attr

With dojo.attr you can access or change the value of an attribute or property of any HTML element in your interface.

Exemple:
<pre>
// Get the title of a node
var title = dojo.attr( id, 'title' );
// Change the height of a node
dojo.attr( 'img_growing_tree', 'height', 100 );
</pre>

'''Vanilla JS attr'''

$(token).id=new_id; // set attr for "id"
var id = $(token).id; // get

=== Queries ===

'''dojo.query(cssSelector: string): Element[]'''

With dojo.query, you can query a bunch of HTML elements with a single function, with a "CSS selector" style.

Example:
<pre>
// All elements with class "possibleMove":
var elements = dojo.query( '.possibleMove' );

// Count number of tokens (i.e., elements of class "token") on the board (i.e., the element with id "board"):
dojo.query( '#board .token' ).length;
</pre>

But what is really cool with dojo.query is that you can combine it with almost all methods above.

Examples:
<pre>
// Trigger a method when the mouse enter in any element with class "meeple":
dojo.query( '.meeple' ).connect( 'onmouseenter', this, 'myMethodToTrigger' );

// Hide all meeples who are on the board
dojo.query( '#board .meeple' ).style( 'display', 'none' );
</pre>

'''Vanilla JS query'''

var cards=document.querySelectorAll(".hand .card");// all cards in all hands
var cards=$('hand').querySelectorAll(".card");// all cards in specific hand
var card=document.querySelector(".hand .card");// first card or null if none (super handy)

=== Creating and Destroying elements ===

'''dojo.empty(node: ElementOrId)'''

Remove all children of the node element
dojo.empty('my_hand');

'''dojo.destroy(node: ElementOrId)'''

Remove the element
dojo.destroy('my_token');

dojo.query(".green", mynode).forEach(dojo.destroy); // this remove all subnode of class green from mynode

'''dojo.create(tag: string, attributes?: obj, parent?: ElementOrId): Element'''

Create element

dojo.create("div", { class: "yellow_arrow" }, parent); // this creates div with class yellow_array and places it in "parent"

'''this.format_block(name: string, args: object): string'''

This bga function that takes global var from template file and substitute variables, typical use would be

var player = gamedatas.players[player_id];
var div = this.format_block('jstpl_player_board', player ); // var jstpl_player_board = ... is defined in .tpl file
Note: result is trimmed

'''this.format_string(name: string, args: object): string'''
This bga function just substitute variables in a string, i.e.
<pre>
var div = this.format_string('<div color="${player_color}"></div>', {player_color: '#ff0000'} );
</pre>
Note: result is trimmed

Note: this can be replaced by using backquoted string now:
const player_color = '#ff0000';
const div = `<div color="${player_color}"></div>`;

'''this.format_string_recursive'''
This bga function is similar to this.format_string but is capable of processing recursive argument structures and translations. It is used to format server notifications.

TODO: find better place for these function docs

=== Moving elements ===

'''dojo.place(node: string | Element, refNode: ElementOrId, pos?: string | number): Element'''

dojo.place is the best function to insert HTML code somewhere in your game interface without breaking something. It is much better to use than the '''innerHTML=''' method if you must insert HTML tags and not only values.

node:

Can be a String or a DOM node. If it is a string starting with “<”, it is assumed to be an HTML fragment, which will be created. Otherwise it is assumed to be an id of a DOM node.

<pre>
// Insert your HTML code as a child of a container element
dojo.place( "<div class='foo'></div>", "your_container_element_id" );
</pre>

pos:

Optional argument. Can be a number or one of the following strings: “before”, “after”, “replace”, “only”, “first”, or “last”. If omitted, “last” is assumed.

"replace": Replace the container element with my_node element

"first": Places the node as a child of the reference node. The node is placed as the first child.

"last" (default): Places the node as a child of the reference node. The node is placed as the last child.

"before": places the node right before the reference node.

"after": places the node right after the reference node.

"only": replaces all children of the reference node with the node.

positive integer: This parameter can be a positive integer. In this case, the node will be placed as a child of the reference node with this number (counting from 0). If the number is more than number of children, the node will be appended to the reference node making it the last child.

<pre>
// Replace all children of container with my_node
dojo.place( $('my_node'), "your_container_element_id", "only" );
</pre>

See also full doc on dojo.place: [https://dojotoolkit.org/reference-guide/1.7/dojo/place.html]

Usually, when you want to insert some piece of HTML in your game interface, you should use "[[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl#Javascript_templates|Javascript templates]]".

But you can also relocate elements like that. Note: it won't animate if you do that.

'''this.placeOnObject(mobile_obj: ElementOrId, target_obj: ElementOrId): void'''

places mobile_obj on target_obj, set the absolute positions and centers the mobile_obj on target_obj,
effect is immediate

This is not really an animation, but placeOnObject is frequently used before starting an animation.

Example:
<pre>
// (We just created an object "my_new_token")

// Place the new token on current player board
this.placeOnObject( "my_new_token", "overall_player_board_"+this.player_id );

// Then slide it to its position on the board
this.slideToObject( "my_new_token", "a_place_on_board" ).play();
</pre>

'''this.placeOnObjectPos(mobile_obj: ElementOrId, target_obj: ElementOrId, target_x: number, target_y: number): void'''

This method works exactly like placeOnObject, except than you can specify some (x,y) coordinates (in px). This way, the center of "mobile_obj" will be placed to the specified x,y position relatively to the center of "target_obj".

''Note: the placement works differently from this.slideToObjectPos'', since coordinates are calculated based on the center of objects.

'''this.attachToNewParent(mobile_obj: ElementOrId, target_obj: ElementOrId): void'''

With this method, you change the HTML parent of "mobile_obj" element without moving it.
"target_obj" is the new parent of this element. The beauty of
attachToNewParent is that the mobile_obj element DOES NOT MOVE during this process.

What happens is that the method calculate a relative position of mobile_obj to make sure it does not move after the HTML parent changes.

Why using this method?

Changing the HTML parent of an element can be useful for the following reasons:
* When the HTML parent moves, all its child are moving with them. If some game elements is no more linked with a parent HTML object, you may want to attach it to another place.
* The z_order (vertical order of display) depends on the position in the DOM, so you may need to change the parent of some game elements when they are moving in your game area.

'''CAREFUL''': this function destroys original object and places a clone onto a new parent, this will break all references to this HTML element (ex: dojo.connect).
If you need version that does not destroy the object but the same otherwise see [[BGA_Studio_Cookbook#Attach_to_new_parent_without_destroying_the_object]]

== Animations ==

===Dojo Animations===

BGA animations is based on Dojo Animation ([http://dojotoolkit.org/documentation/tutorials/1.8/animation/ see tutorial here]).

However, most of the time, you can just use methods below, which are built on top of Dojo Animation.

Note: one interesting method from Dojo that could be useful from time to time is "Dojo.Animation". It allows you to make any CSS property "slide" from one value to another.

Note 2: the slideTo methods are not compatible with CSS transform (scale, zoom, rotate...). If possible, avoid using CSS transform on nodes that are being slided. Eventually, the only possible solution to make these 2 compatible is to disable all CSS transform properties, use slideToObjectPos/placeOnObjectPos, and then apply them again.

===Sliding===

'''this.slideToObject(mobile_obj: ElementOrId, target_obj: ElementOrId, duration?: number, delay?: number): Animation'''

You can use slideToObject to "slide" an element to a target position.

Sliding element on the game area is the recommended and the most used way to animate your game interface. Using slides allow players to figure out what is happening on the game, as if they were playing with the real boardgame.

The parameters are:
* mobile_obj: the ID of the object to move. This object must be "relative" or "absolute" positioned.
* target_obj: the ID of the target object. This object must be "relative" or "absolute" positioned. Note that it is not mandatory that mobile_obj and target_obj have the same size. If their size are different, the system slides the center of mobile_obj to the center of target_obj.
* duration: (optional) defines the duration in millisecond of the slide. The default is 500 milliseconds.
* delay: (optional). If you defines a delay, the slide will start only after this delay. This is particularly useful when you want to slide several object from the same position to the same position: you can give a 0ms delay to the first object, a 100ms delay to the second one, a 200ms delay to the third one, ... this way they won't be superposed during the slide.

BE CAREFUL: The method returns an dojo.fx animation, so you can combine it with other animation if you want to. It means that you have to call the "play()" method, otherwise the animation WON'T START.

Example:
<pre>
this.slideToObject( "some_token", "some_place_on_board" ).play();
</pre>

'''this.slideToObjectPos(mobile_obj: ElementOrId, target_obj: ElementOrId, target_x: number, target_y: number, duration?: number, delay?: number): Animation'''

This method does exactly the same as "slideToObject", except than you can specify some (x,y) coordinates. This way, "mobile_obj" will slide to the specified x,y position relatively to "target_obj".

Example: slide a token to some place on the board, 10 pixels from the top:
<pre>
this.slideToObjectPos( "some_token", "some_place_on_board", 0, 10 ).play();
</pre>

'''this.slideTemporaryObject(mobile_obj_html: string, parent: ElementOrId, from: ElementOrId, to: ElementOrId, duration?: number, delay?: number): Animation'''

This method is useful when you want to slide a temporary HTML object from one place to another. As this object does not exists before the animation and won't remain after, it could be complex to create this object (with dojo.place), to place it at its origin (with placeOnObject) to slide it (with slideToObject) and to make it disappear at the end.

slideTemporaryObject does all of this for you:
* mobile_obj_html is a piece of HTML code that represent the object to slide.
* parent is the ID of an HTML element of your interface that will be the parent of this temporary HTML object.
* from is the ID of the origin of the slide.
* to is the ID of the target of the slide.
* duration/delay works exactly like in "slideToObject"

Example:
<pre>
this.slideTemporaryObject( '<div class="token_icon"></div>', 'tokens', 'my_origin_div', 'my_target_div' ).play();
</pre>

===Destroy===
'''this.slideToObjectAndDestroy(mobile_obj: ElementOrId, target_obj: ElementOrId, duration?: number, delay?: number): void'''

This method is a handy shortcut to slide an existing HTML object to some place then destroy it upon arrival. It can be used for example to move a victory token or a card from the board to the player panel to show that the player earns it, then destroy it when we don't need to keep it visible on the player panel.

It works the same as this.slideToObject and takes the same arguments, but it starts the animation.

CAREFUL: Make sure nothing is creating the same object at the same time the animation is running, because this will cause some random disappearing effects

Example:
<pre>
this.slideToObjectAndDestroy( "some_token", "some_place_on_board", 1000, 0 );
</pre>

'''this.fadeOutAndDestroy( node: string | Element, duration?: number, delay?: number):''' '''void'''

This function fade out the target node, then destroy it. Its starts the animation.
* duration/delay works exactly like in "slideToObject"

Example:
<pre>
this.fadeOutAndDestroy( "a_card_that_must_disappear" );
</pre>

CAREFUL: the HTML node still exists until during few milliseconds, until the fadeOut has been completed.
Make sure nothing is creating same object at the same time as animation is running, because you will be some random dissapearing effects

===Rotating elements===

This example combines "Dojo.Animation" method and a CSS property transform that allow you to rotate the element.
<pre>
// node is Element we rotating
var animation = new dojo.Animation({
curve: [fromDegree, toDegree],
onAnimate: (v) => {
node.style.transform = 'rotate(' + v + 'deg)';
}
});

animation.play();
</pre>

BGA has its own interface to rotate

'''this.rotateTo(node: string | Element, degree: number): void'''

It starts the animation, and stored the rotation degree in the class, so next time you rotate object - it is additive.
There is no animation hooks in this one, if you need to change any parameters use dojo animation above.

There is also '''rotateInstantTo''' with same signature which does not animate

===Animation Callbacks===

If you wish to run some code only after an animation has completed you can do this by linking a callback method to 'onEnd'.

<pre>
var animation_id = this.slideToObject( mobile_obj, target_obj, 500 );
dojo.connect(animation_id, 'onEnd', () => {
// do something here
});
animation_id.play();
</pre>

If you wish to call a second animation after the first (rather than general code) then you can use a dojo animation chain (see tutorial referenced above).

== Players input ==

=== Connecting ===
'''dojo.connect(element: Element, event: string, context: object, method: eventHandler): any'''

'''dojo.connect(element: Element, event: string, hander: eventHandler): any'''

Used to associate a player event with one of your notification methods.

Example: associate a click on an element ("my_element") with one of our methods ("onClickOnMyElement"):
<pre>
dojo.connect( $('my_element'), 'onclick', this, 'onClickOnMyElement' );
</pre>

Same idea but base on query (i.e. all element of 'pet' class)
dojo.query(".pet").connect('onclick', this, 'onPet');

Note: if you need to disconnect the handler you have to store handler returned from this method, i.e.

<pre>
var handler = dojo.connect(...);
...
dojo.disconnect(handler);
</pre>

If you don't store the handler - you have to destroy the object to disconnect it

Typical function that implements the input handler will look like this

<pre>
onPet: function(event) {
var id = event.currentTarget.id;
console.log('onPet ' + id);
dojo.stopEvent(event);
if (this.gamedatas.gamestate.name == 'playerTurnPet') {
this.bgaPerformAction('actPlayPet', {card: id});
} else {
this.showMoveUnauthorized();
}
}
</pre>

'''this.connect(element: ElementOrId, event: string, method: eventHandler): void'''

Used to associate a player event with one of your notification methods.

this.connect( $('my_element'), 'onclick', 'onClickOnMyElement' );

Or you can use an in-place handler

this.connect( $('my_element'), 'onclick', (e) => { console.log('boo'); } );

Note that this function stores the connection handler. That is the only real difference between '''this.connect''' and '''dojo.connect'''. If you plan to destroy the element you connected, you '''must''' call this.disconnect() to prevent memory leaks.
This function is mainly for permanent objects - if you just want to connect the temp object you should probably not use this method but use dojo.connect which won't require any clean-up.

'''this.connectClass(cssClassName: string, event: string, method: eventHandler): void'''

Same as connect(), but for all the nodes set with the specified cssClassName.

this.connectClass('pet', 'onclick', 'onPet');

'''this.disconnect(element: ElementOrId, event: string): void'''

Disconnect event handler (previously registered with this.connect or this.connectClass).

this.disconnect( $('my_element'), 'onclick');

Note: dynamic connect/disconnect is for advanced cases ONLY, you should always connect elements statically if possible, i.e. in setup() method.

'''this.disconnectAll(): void'''

Disconnect all previously registed event handlers (registered via this.connect or this.connectClass)

this.disconnectAll();

=== Actions ===

'''this.bgaPerformAction(action: string, args?: object, options: object = { lock: true, checkAction: true }): Promise<void>'''

Triggers an action on the backend. This is a combination of checkAction and ajaxcall, returning a Promise which resoves when ajaxcall ends.

This method must be used to send a player input to the game server. '''It should not be triggered programmatically''', especially not in loops, in callbacks, in notifications, or in onEnteringState/onUpdateActionButtons/onLeavingState, in order not to create race conditions or break replay game and tutorial features. It should be used only in reaction to a user action in the interface.

* action: name of the action, as it is written in "possibleactions" of the current state.
* args: an object containing the call parameters to send to the action
* options: options to tweak the call with some defaults. Default is <code>{ lock: true, checkAction: true }</code>.

Example of a standard call without args:
this.bgaPerformAction('pass');

Example of a standard call with action args:
this.bgaPerformAction('actPlayCard', { id: this.selectedCardId });

Example of a call without checking action (because player is inactive in a multiactive state):

this.bgaPerformAction('actChangeMind', {}, { checkAction: false });

Example of a call without lock (because of a special action not directly related to the game flow):

this.bgaPerformAction('actSetAutoBid', { alwaysBidUntil: 500 }, { lock: false, checkAction: false });

Example of call with reaction to exception:
this.bgaPerformAction('actPlayCard', { id: this.selectedCardId }).catch(()=>{ this.selectedCardId = undefined; });

Example of call with reaction to success:
this.bgaPerformAction('actPlayCard', { id: this.selectedCardId }).then(()=>{ this.unselectAll(); });

'''this.ajaxcall(url, parameters, obj_callback, callback, callback_anycase?, ajax_method?: string)'''

''Note: bgaPerformAction is a simpler way to use ajax calls, ajaxcall stays in the doc for legacy reasons only and should not be used in new projects.''

Same warning as '''this.bgaPerformAction''' about using on user action only.

* url: the url of the action to perform. For a game, it must be: "/<mygame>/<mygame>/myAction.html"
* parameters: an array of parameter to send to the game server.
** Note that "lock: true" must always be specified in this list of parameters in order the interface can be locked during the server call. Cannot use lock: false - to not lock it has to be undefined.
** Note: Restricted parameter names (please don't use them):
*** "action"
*** "module"
*** "class"
* obj_callback: must be set to "this".
* callback (non-optional but rarely used): a function to trigger when the server returns result and everything went fine (not used, as all data handling is done via notifications).
* callback_anycase: (optional) a function to trigger when the server returns ok OR error. If no error this function is called with parameter value false. If an error occurred, the first parameter will be set to true, the second will contain the error message sent by the PHP back-end, and the third will contain an error code.
* ajax_method: (optional and rarely used) if you need to send large amounts of data (over 2048 bytes), you can set this parameter to 'post' (all lower-case) to send a POST request as opposed to the default GET. This works, but was not officially documented, so only use if you really need to.

Usage:
<pre>
this.ajaxcall( '/mygame/mygame/actMyAction.html', { lock: true,
arg1: myarg1,
arg2: myarg2
}, this, (result)=>{} );
</pre>

'''this.checkAction(action: string, nomessage?: boolean): boolean '''

Check if player can do the specified action by taking into account:
* if interface is locked it will return false and show message "An action is already in progress", unless nomessage set to true
* if player is not active it will return false and show message "This is not your turn", unless nomessage set to true
* if action is not in list in possible actions (defined by "possibleaction" in current game state) it will return false and show "This move is not authorized now" error (unconditionally).
* otherwise returns true
Example:
<pre>
function onClickOnGameElement( evt ) {
if( this.checkAction( "actMyAction" ) ) {
// Do the action
}
}
</pre>

'''this.checkPossibleActions(action: string): boolean'''

* this is independent of the player being active, so can be used instead of this.checkAction(). This is particularly useful for multiplayer states when the player is not active in a 'player may like to change their mind' scenario. Unlike this.checkAction, this function does NOT take interface locking into account

* if action is not in list in possible actions (defined by "possibleaction" in current game state) it will return false and show "This move is not authorized now" error (unconditionally).
* otherwise returns true

function onChangeMyMind( evt ) {
if( this.checkPossibleActions( "actMyAction" ) ) {
// Do the action
}
}

'''this.checkLock(nomessage?: boolean): boolean'''

When using "lock: true" in ajax call you can use this function to check if interface is in lock state (it will be locked during server call and notification processing).
This check can be used to block some other interactions which do not result in ajaxcall or if you want to suppress errors. Note: normally you only need to use this.checkAction(...), this is for advanced cases.

It will also show error unless nomessage is set to true

function onChangeMyMind( evt ) {
if( this.checkLock() ) {
// Do the action
}
}

== Notifications ==

When something happens on the server side, your game interface Javascript logic received a notification.
If you have not done so yet check what notification are in [[Main_game_logic:_yourgamename.game.php#Notifications]]

Here's how you can handle these notifications on the client side.

=== Subscribe to notifications ===

'''dojo.subscribe(notif_type: string, callback_obj: Object, handler: string|handler)'''
* notif_type - notification type/name send by php server
* callback_obj - usually this
* handler - if string method of callback_obj with name name is called, when notification is called, with notification object as parameter (see below)

Your Javascript "setupNotifications" method is the place where you can subscribe to notifications from your PHP code.

Here's how you associate one of your Javascript method to a notification "playDisc" (from Reversi example):

<pre>
setupNotifications: function() {
...
dojo.subscribe('playDisc', this, "notif_playDisc");
},
</pre>

Note: the "playDisc" corresponds to the name of the notification you define it in your PHP code, in your "notifyAllPlayers" or "notifyPlayer" method.

Then, you have to define your "notif_playDisc" method:

<pre>
notif_playDisc: function(notif) {
// Remove current possible moves (makes the board more clear)
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );
this.addDiscOnBoard( notif.args.x, notif.args.y, notif.args.player_id );
},
</pre>

In a notification handler like our "notif_playDisc" method, you can access all notifications arguments with "notif.args".

Example:

PHP

<pre>
$this->notifyAllPlayers( "apples", clienttranslate('player takes ${count} apples'), [ "count" => 3 ] );
</pre>

JavaScript

<pre>
setupNotifications: function() {
dojo.subscribe( 'apples', this, 'notif_apples' );
},

notif_apples: function(notif) {
//You can access the "count" like this:
alert("count = " + notif.args.count);
}
</pre>

=== The notification Object received by client ===

When sending a notification on your PHP, the client side will receive an Object with the following attributes:

* type - type of the notification (as passed by php function)
* log - the log string passed from php notification
* args - This is the arguments that you passed on your notification method on php
* bIsTableMsg - is true when you use [[Main_game_logic:_yourgamename.game.php#NotifyAllPlayers|NotifyAllPlayers]] method (false otherwise)
* channelorig - information about table ID (formatted as : "/table/t[TABLE_NUMBER]")
* gamenameorig - name of the game
* move_id - ID of the move associated with the notification
* table_id - ID of the table (comes as string)
* time - UNIX GMT timestamp
* uid - unique identifier of the notification
* h - unknown

'' Note that those information were inferred from observation on console log. If an Admin can confirm/correct (and remove this line), you're welcome :)''

=== Ignoring notifications ===

Sometimes you need to ignore some notification on client side. You don't want them to be shown in game log and you don't want them to be handled.

The most common use case is when a player gets private information. They will receive a specific notification (such as "You received Ace of Heart"), while other players would receive more generic notification ("Player received a card").

In X.game.php
<pre>
$this->notifyAllPlayers("dealCard", clienttranslate('${player_name} received a card'), [
'player_id' => $playerId,
'player_name' => $this->getActivePlayerName()
]);

$this->notifyPlayer($playerId, "dealCardPrivate", clienttranslate('You received ${cardName}'), [
"type" => $card["type"],
"cardName" => $this->getCardName($card["type"])
]);
</pre>

The problem with this approach is that the active player will receive two notifications:
* Player1 received a card
* You received Ace of Hearts

Hence, notification ignoring.

NOTE: You can think that it would be possible to send such notification to all players except active just by using notifyPlayer and it seems to work. The problem however is that table spectators would miss such notification and their user interface (and game log) wouldn't be updated. Since there is no way to send notification just to spectators, ignoring the notification (or "filtering") is the only reasonable solution.

'''setIgnoreNotificationCheck(notif_type: string, predicate: ((notif: Notif)=>boolean))'''
This method will set a check whether any of notifications of specific type should be ignored.

The parameters are:
* notif_type: type of the notification
* predicate (notif => boolean): a function that will receive notif object and will return true if this specific notification should be ignored

Before dispatching any notification of this type, the framework will call predicate to check whether notification should be ignored, if it return true - the notification will be dispatched, i.e. logged or handled.

<pre>
this.notifqueue.setIgnoreNotificationCheck( 'dealCard', (notif) => (notif.args.player_id == this.player_id) );
</pre>

IMPORTANT: Remember that this notification is ignored on the client side, but was still received by the client. Therefore it shouldn't contain any private information as cheaters can get it. In other words this is not a way to hide information.

IMPORTANT: When a game is reloaded with F5 or when opening a turn based game, old notifications are replayed as history notification. They are used just to update the game log and are stripped of all arguments except player_id, i18n and any argument present in message. If you use and other argument in your predicate you should '''preserve''' it as explained [[Main_game_logic:_yourgamename.game.php#Notify_players|here]].

=== Synchronous notifications ===

When several notifications are received by your game interface, these notifications are processed immediately, one after the other, in the same exact order they have been generated in your PHP game logic.

However, sometimes, you need to give some time to the players to figure out what happened on the game before jumping to the next notification. Indeed, in many games, there are a lot of automatic actions, and the computer is going to resolve all these actions very fast if you don't tell it not to do so.

As an example, for Reversi, when someone is playing a disc, we want to wait 500 milliseconds before doing anything else in order the opponent player can figure out what move has been played.

Here's how we do this, right after our subscription:
<pre>
dojo.subscribe( 'playDisc', this, "notif_playDisc" );
this.notifqueue.setSynchronous( 'playDisc', 500 ); // Wait 500 milliseconds after executing the playDisc handler
</pre>

-----

It is also possible to control the delay timing dynamically (e.g., using notification args). As an example, maybe your notification 'cardPlayed' should pause for a different amount of time depending on the number or type of cards played.

For this case, use '''setSynchronous''' without specifying the duration and use '''setSynchronousDuration''' within the notification callback.

* NOTE: If you forget to invoke '''setSynchronousDuration''', the game will remain paused forever!

<pre>
setupNotifications: function () {
dojo.subscribe( 'cardPlayed', this, 'notif_cardPlayed' );
this.notifqueue.setSynchronous( 'cardPlayed' ); // wait time is dynamic
...
},

notif_cardPlayed: function (notif) {
// MUST call setSynchronousDuration

// Example 1: From notification args (PHP)
this.notifqueue.setSynchronousDuration(notif.args.duration);
...

// Or, example 2: Match the duration to a Dojo animation
var anim = dojo.fx.combine([
...
]);
anim.play();
this.notifqueue.setSynchronousDuration(anim.duration);
},
</pre>

You can also manually call this.notifqueue.setSynchronousDuration(0) once client operations are finished, but be careful that even fast replay still has a path to call it.

'''WARNING: combining synchronous and ignored notifications'''
You must be careful when combining dynamic synchronous durations (as described above) with ignored notifications. If you have a conditionally ignored notification like this (see below section):

<pre>this.notifqueue.setIgnoreNotificationCheck( 'myNotif', (notif) => (notif.args.player_id == this.player_id) /* or any other condition */ )</pre>

then you CANNOT do

<pre>this.notifqueue.setSynchronous('myNotif');</pre>

as, when the ignored check passes, the notification handler, in which `this.notifqueue.setSychronousDuration` is called, is never called and so the duration is never set and interface locking results.

The workaround is to set a "dummy" time:

<pre>this.notifqueue.setSynchronous('myNotif', 5000);</pre>

whose value is irrelevant but must be large enough to cover the time before the notification handler is called. The large value never actually comes into play because the notification is either ignored, or the synchronous duration is reset to a sensible value inside the handler.

=== Pre-defined notification types ===

'''tableWindow''' - This defines notification to display [[Game_interface_logic:_yourgamename.js#Scoring_dialogs|Scoring Dialogs]], see below.

'''message''' - This defines notification that shows on players log and have no other effect (technically any unhandled notification will do the same but its recommended to use this keyword for consistency)

// You can call this on php side without doing anything on client side
self::notifyAllPlayers( 'message', clienttranslate('hello'), [] );

'''simplePause''' - This notification will just delay other notifications, maybe useful if you know you need some extra time for animation or something. Requires a time parameter.

<pre>
self::notifyAllPlayers( 'simplePause', '', [ 'time' => 500] ); // time is in milliseconds
</pre>

Note: the following types are RESERVED by framework, do not use:

gameStateChange gameStateChangePrivateArg gameStateMultipleActiveUpdate newActivePlayer playerstatus yourturnack clockalert tableInfosChanged playerEliminated tableDecision archivewaitingdelay end_archivewaitingdelay replaywaitingdelay end_replaywaitingdelay replayinitialwaitingdelay end_replayinitialwaitingdelay aiPlayerWaitingDelay replay_has_ended updateSpectatorList wouldlikethink updateReflexionTime undoRestorePoint resetInterfaceWithAllDatas zombieModeFail zombieModeFailWarning aiError skipTurnOfPlayer zombieBack allPlayersAreZombie gameResultNeutralized playerConcedeGame showTutorial showCursor showCursorClick skipTurnOfPlayerWarning banFromTable resultsAvailable switchToTurnbased newPrivateState infomsg

== Tooltips ==

=== Adding static tooltips ===

'''this.addTooltip(nodeId: string, helpStringTranslated: string, actionStringTranslated: string, delay?: number): void'''

Add a simple text tooltip to the DOM node.

Specify 'helpStringTranslated' to display some information about "what is this game element?".
Specify 'actionStringTranslated' to display some information about "what happens when I click on this element?".

You must specify both of the strings. You can only use one and specify an empty string ('') for the other one.

When you pass text directly function _() must be used for the text to be marked for translation! Except for empty string.

Parameter "delay" is optional. It is primarily used to specify a zero delay for some game element when the tooltip gives really important information for the game - but remember: no essential information must be placed in tooltips as they won't be displayed in some browsers (see [[BGA_Studio_Guidelines|Guidelines]]).

Example:
<pre>
this.addTooltip( 'cardcount', _('Number of cards in hand'), '' );
</pre>

Note: this generates static tooltip and attaches to existing dom element, if you need to generate tooltip more dynamically you have to call that method every time information about object is updated or use completely different tehnique, see dynamic tooltips below.

'''this.addTooltipHtml(nodeId: string, html: string, delay?: number): void'''

Add an HTML tooltip to the DOM node (for more elaborate content such as presenting a bigger version of a card).

'''this.addTooltipToClass(cssClass: string, helpStringTranslated: string, actionStringTranslated: string, delay?: number ): void'''

Add a simple text tooltip to all the DOM nodes set with this cssClass. See more details above for this.addTooltip.
this.addTooltipToClass( 'meeple', _('This is A Meeple'), _('Click to tickle') );

IMPORTANT: all concerned nodes must exist and have IDs to get tooltips.

'''this.addTooltipHtmlToClass(cssClass: string, html: string, delay?: number): void'''

Add an HTML tooltip to to all the DOM nodes set with this cssClass (for more elaborate content such as presenting a bigger version of a card).

IMPORTANT: all concerned nodes must exist and have IDs to get tooltips.

=== Removing static tooltips ===

'''this.removeTooltip(nodeId: string): void'''

Remove a tooltip from the DOM node with given id.

=== Advanced tooltips ===

'''force tooltip to open'''

If you want to force tooltip to open in reaction to some other action, i.e. click you can do this

this.tooltips[id].open(id)

where id is the id of the tooltip node where tooltip was installed.

'''dynamic tooltips'''

See [[BGA_Studio_Cookbook#Dynamic_tooltips]]

'''tooltips on mobile'''

Tooltips is very unreliable on mobile, it is recommended to implement some other method to obtaining same information,
such as simple click handler in dedicated "Help" mode or provide dedicated clickable areas such as corner of card.

== Warning messages ==

Sometimes, there is something important that is happening in the game and you have to make sure all players get the message. Most of the time, the evolution of the game situation or the game log is enough, but sometimes you need something more visible.

Ex: someone fulfills one of the end of the game conditions, so this is the last turn.

'''this.showMessage(msg: string, type: string): void'''

showMessage shows a message in a big rectangular area on the top of the screen of the current player, and it dissapears after few seconds (also it will be in the log in some cases).

* "msg" is the string to display. It should be translated.
* "type" can be set to "info", "error", "only_to_log" or custom string. If set to "info", the message will be an informative message on a white background. If set to "error", the message will be an error message on a red background and it will be added to log. If set to "only_to_log", the message will be added to the game log but will not popup at the top of the screen.
If set to custom string, it will be transparent, to use custom type define "head_xxx" in css, where xxx is the type. For example if you want yellow warning, use "warning" as type and add this to css:
.head_warning {
background-color: #e6c66e;
}

Important: the normal way to inform players about the progression of the game is the game log. The "showMessage" is intrusive and should not be used often.

<pre>
notif_messageinfo: function(notif) {
if (!g_archive_mode) {
var message = this.format_string_recursive(notif.log, notif.args);
this.showMessage(_('Announcement:') + " " + message, 'info');
}
},
</pre>

Show message could be used on the client side to prevent user wrong moves before it is send to server.
Example from 'battleship':
<pre>
onGrid: function(event) {
if (checkIfPlayerTriesToFireOnThemselves(event)) {
this.showMessage(_('This is your own board silly!'), 'error');
return;
}
...
},
</pre>

'''this.showMoveUnauthorized(): void'''

Shows predefined user error that move is unauthorized now

<pre>
onPet: function(event) {
if (checkPet(event)==false) {
this.showMoveUnauthorized();
return;
}
...
},
</pre>

== Dialogs ==

=== Confirmation dialog ===

When an important action with a lot of consequences is triggered by the player, you may want to propose a confirmation dialog.

CAREFUL: the general guideline of BGA is to AVOID the use of confirmation dialogs. Confirmation dialogs slow down the game and bother players. The players know that they have to pay attention to each move when they are playing online.

The situations where you should use a confirmation dialog are the following:
* It must not happen very often during a game.
* It must be linked to an action that can really "kill a game" if the player does not pay attention.
* It must be something that can be done by mistake (ex: a link on the action status bar).

'''this.confirmationDialog(message: string, yesHandler: (param: any) => void, noHandler?: (param: any) => void, param?: any): void'''

* message - message will be shown to user, use _() to translate
* yesHandler - non-optional handler to be called on yes
* noHandler - optional handler to called on no
* param - if specified, it will be passed to both handlers
NOTE: this is async function, it does not return anything and you should not do anything after, you must do everything in handlers

How to display a confirmation dialog:
<pre>
this.confirmationDialog(_("Are you sure you want to bake a pie?"), () => {
this.bakeThePie();
});
return; // nothing should be called or done after calling this, all action must be done in the handler
</pre>
With param and both handlers
<pre>
this.confirmationDialog(_("Are you sure you want to bake a pie?"),
(ingredient) => this.bakeThePie(ingredient),
(ingredient) => console.log(`cancelled baking of ${ingredient}`),
'apple');
</pre>

=== Multiple choice dialog ===

You can use this dialog to give user a choice with small amount of options

'''this.multipleChoiceDialog(message: string, choices: string[], callback: (choice: number) => void): void'''
* message - message will be shown to user, use _() to translate
* choices - array of choices
* callback - non-optional handler to be called on choice made, the choice parameter is the INDEX of the choice from the array of choices

NOTE: this is async function, it does not return anything and you should not do anything after, you must do everything in handlers
NOTE: there is no cancel handler, so make sure you gave user a choice to get out of it

Example:
<pre>
const keys = ["0", "1", "5", "10"];
this.multipleChoiceDialog(_("How many bugs to fix?"), keys, (choice) => {
if (choice==0) return; // cancel operation, do not call server action
var bugchoice = keys[choice]; // choice will be 0,1,2,3 here
this.bgaPerformAction("fixBugs", { number: bugchoice });
});
return; // must return here
</pre>

=== Generic Dialogs ===

As a general rule, you shouldn't use dialogs windows.

BGA guidelines specify that all game elements should be displayed on the main screen. Players can eventually scroll down to see game elements they don't need to see anytime, and you may eventually create anchors to move between game area section. Of course dialogs windows are very practical, but the thing is: all players know how to scroll down, and not all players know how to show up your dialog window. In addition, when the dialog shows up, players can't access the other game components.

Sometimes although, you need to display a dialog window. Here is how you do this:

// Create the new dialog over the play zone. You should store the handler in a member variable to access it later
this.myDlg = new ebg.popindialog();
this.myDlg.create( 'myDialogUniqueId' );
this.myDlg.setTitle( _("my dialog title to translate") );
this.myDlg.setMaxWidth( 500 ); // Optional

// Create the HTML of my dialog.
// The best practice here is to use [[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl#Javascript_templates|Javascript templates]]
var html = this.format_block( 'jstpl_myDialogTemplate', {
arg1: myArg1,
arg2: myArg2,
...
} );

// Show the dialog
this.myDlg.setContent( html ); // Must be set before calling show() so that the size of the content is defined before positioning the dialog
this.myDlg.show();

// Now that the dialog has been displayed, you can connect your method to some dialog elements
// Example, if you have an "OK" button in the HTML of your dialog:
dojo.connect($('my_ok_button'), 'onclick', this, (event) => {
event.preventDefault();
this.myDlg.destroy();
});

If necessary, you can remove the default top right corner 'close' icon, or replace the function called when it is clicked:
// Removes the default close icon
this.myDlg.hideCloseIcon();

// Replace the function call when it's clicked
this.myDlg.replaceCloseCallback((event) => { ... });

=== Scoring dialogs ===

Sometimes at the end of a round you want to display a big table that details the points wins in each section of the game.

Example: in Hearts game, we display at the end of each round the number of "heart" cards collected by each player, the player who collected the Queen of Spades, and the total number of points loose by each player.

Scoring dialogs are managed entirely on '''PHP side''', but they are described here as their effects are visible only on client side.

Displaying a scoring dialog is quite simple and is using a special notification type: "tableWindow":
<pre>
// on PHP side:
$this->notifyAllPlayers( "tableWindow", '', array(
"id" => 'finalScoring',
"title" => clienttranslate("Title of the scoring dialog"),
"table" => $table
));
</pre>

The "table" argument is a 2 dimensional PHP array that describes the table you want to display, line by line and column by column.

Example: display an 3x3 array of strings
<pre>
$table = [
[ "one", "two", "three" ], // This is my first line
[ "four", "five", "six" ], // This is my second line
[ "seven", "height", "nine" ] // This is my third line
];
</pre>

As you can see above, in each "cell" of your array you can display a simple string value. But you can also display a complex value with a template and associated arguments like this:
<pre>
$table = [
[ "one", "two", [ "str" => clienttranslate("a string with an ${argument}"), "args" => [ 'argument' => 'argument_value' ] ] ],
[ "four", "five", "six" ],
[ "seven", "height", "nine" ]
];
</pre>

This is especially useful when you want to display player names with colors. Example from "Hearts":
<pre>
$firstRow = [ '' ];
foreach( $players as $player_id => $player ) {
$cell = [ 'str' => '${player_name}',
'args' => [ 'player_name' => $player['player_name'] ],
'type' => 'header'
];
$firstRow[] = $cell;
}
$table[] = $firstRow;
...
</pre>

You can also use three extra attributes in the parameter array for the notification:
* '''header''': the content for this parameter displays before the table (also, the html will be parsed and player names will be colored according to the current game colors).
* '''footer''': the content for this parameter displays after the table (no parsing for coloring the player names)
* '''closing''': if this parameter is used, a button will be displayed with this label at the bottom of the popup and will allow players to close it (more easily than by clicking the top right 'cross' icon).

<pre>
$this->notifyAllPlayers( "tableWindow", '', [
"id" => 'finalScoring',
"title" => clienttranslate("Title of the scoring dialog"),
"table" => $table,
"header" => ['str' => clienttranslate('Table header with parameter ${number}'),
'args' => [ 'number' => 3 ],
],
"footer" => '<div class="myfoot"></div>',
"closing" => clienttranslate( "Closing button label" )
] );
</pre>

Note: currently id is not used - so you cannot access resulting div by id on js side
Note: any traslatable stirng have to be wrapped by clienttranslate() on top level OR it has to be recursive template.

DO NOT DO THIS:
<pre>
"footer" => '<div>'.clienttranslate( "The end" ).'</div>', // this will not work for translations!!!
</pre>

=== Scoring animated display ===

Sometimes, you may want to display a score value over an element to make the scoring easier to follow for the players (Terra Mystica final scoring for example).
You can do it with:

'''this.displayScoring(anchor_id: string, color: string, score: number | string, duration?: number, offset_x?: number, offset_y?: number): void'''

'''anchor_id''': ID of the html element to place the animated score onto (without the '#')

'''color''': hexadecimal RGB representation of the color (should be the color of the scoring player), but without a leading '#'. For instance, 'ff0000' for red.

'''score''': numeric score to display, prefixed by a '+' or '-'

'''duration''': animation duration in milliseconds (optional, default is 1000)

'''offset_x''' and '''offset_y''': if both offset_x and offset_y are defined and not null, apply the following offset (in pixels) to the scoring animation.
Note that the score is centered in the anchor, so the offsets might have to be negative if you calculate the position.

Note: if you want to display successively each score, you can use ''this.notifqueue.setSynchronous()'' function.
<pre>
setupNotifications: function() {
dojo.subscribe( 'displayScoring', this, "notif_displayScoring" );
...
}
...

notif_displayScoring: function(notif) {
const duration = notif.args.duration?notif.args.duration:1000;
this.notifqueue.setSynchronous('displayScoring', duration );
this.displayScoring( notif.args.target, notif.args.color, notif.args.score, duration);
},
</pre>

=== Speech bubble ===

For better interactivity in some games (Love Letter for example), you may use comic book style speech bubbles to express the players voices.
This is done with showBubble:

'''this.showBubble(anchor_id: string, text: string, delay?: number, duration?: number, custom_class?: string): void'''

* anchor_id - where to attach the bubble
* text - what to put in bubble, can be html
* delay - delay in milliseconds (optional, default 0)
* duration - duration of animation in milliseconds (optional, default 3000)
* custom_class - extra class to add to bubble (optional), if you need to override the default bubble style

<pre>
this.showBubble('meeple_2', _('Hello'), 0, 1000, 'pink_bubble');
</pre>

<pre>
notif_speechBubble(notif) {
var html = this.format_string_recursive(notif.args.text, notif.args.args);
this.showBubble(notif.args.target, html, notif.args.delay ?? 0, notif.args.duration ?? 1000);
},
</pre>

'''Warning''': if your bubble could overlap other active elements of the interface (buttons in particular), as it stays in place even after disappearing, you should use a custom class to give it the style "pointer-events: none;" in order to intercept click events.

Note: If you want this visually, but want to take complete control over this bubble and its animation (for example to make it permanent) you can just use div with 'discussion_bubble' class on it, and content of div is what will be shown.

== Translations ==

See [[Translations]]

== Players panels ==

=== Update players score ===

The column player_score from the player table is automatically loaded into this.scoreCtrl and therefore into the stars location on the player board. This occurs sometime after the game setup() function. However this score must be updated as the game progresses using notifications.

Note: this.scoreCtrl[player_id] is object of class [[Counter]], you can use other counter API.

Increase a player score (with a positive or negative number):

<pre>
this.scoreCtrl[ player_id ].incValue( score_delta );
</pre>

Set a player score to a specific value:

<pre>
this.scoreCtrl[ player_id ].setValue( new_score );
</pre>

Set a player score to a specific value with animation:

<pre>
this.scoreCtrl[ player_id ].toValue( new_score );
</pre>

Typical usage would be (that will process 'score' notification):
<pre>
setupNotifications : function() {
...
dojo.subscribe('score', this, "notif_score");
},
notif_score: function(notif) {
this.scoreCtrl[notif.args.player_id].setValue(notif.args.player_score);
},
</pre>

=== Adding stuff to player's panel ===

At first, create a new "JS template" string in your template (tpl) file:

(from Gomoku example)
<pre>
var jstpl_player_board = '\<div class="cp_board">\
<div id="stoneicon_p${id}" class="gmk_stoneicon gmk_stoneicon_${color}"></div><span id="stonecount_p${id}">0</span>\
</div>';
</pre>

Then, you add this piece of code in your JS file to add this template to each player panel:

<pre>
// Setting up player boards
for( var player_id in gamedatas.players )
{
var player = gamedatas.players[player_id];

// Setting up players boards if needed
var player_board_div = $('player_board_'+player_id);
dojo.place( this.format_block('jstpl_player_board', player ), player_board_div );
}
</pre>

(Note: the code above is of course from your "setup" function in your Javascript).

Very often, you have to distinguish current player and others players. In this case, you just have to create another JS template (ex: jstpl_otherplayer_board) and use it when "player_id" is different than "this.player_id".

=== Fixing Player Panel heights ===

You may find that the player panels don't automatically resize when adding something to (or removing something from) a player panel while the display is in portrait mode (i.e. the player summary panels are at the top of the screen rather than down the right side).

When this happens, call <pre>this.adaptPlayersPanels();</pre> This recalculates the layout and also adjusts the position of the actionbar for you.

=== Player's panel disabling/enabling ===

'''this.disablePlayerPanel(player_id: number): void'''

Disable given player panel (the panel background become gray).

Usually, this is used to signal that this played passes, or will be inactive during a while.

Note that the only effect of this is visual. There are no consequences on the behaviour of the panel itself.

'''this.enablePlayerPanel(player_id:number): void'''

Enable a player panel that has been disabled before.

'''this.enableAllPlayerPanels(): void'''

Enable all player panels that has been disabled before.

=== Player order ===

'''this.updatePlayerOrdering(): void'''

This function makes sure that player order in player's panel matches this.gamedatas.playerorder and its normally called by framework.
You can call it yoursel if you change this.gamedatas.playerorder from notification.
Also you can override this function to change defaults OR insert a non-player panel [[BGA_Studio_Cookbook#Inserting_non-player_panel]].

=== Counters ===
Note: there is bga component called "ebg/counter" this API is not using it, these methods
below declared right in core game. If you need animation for counters use ebg/counter

To use this API just create a counter dom element like this (class does not really matter)
<pre>
<div class="counter" id="bread"></div>
<div class="counter" id="coin"></div>
</pre>
The "bread" will the counter name.

The php code should send all "counters" data from getAllDatas() method like this

game.php
<pre>
protected function getAllDatas() {
// (the key must match counter_name)
$result['counters']=[
'bread' => [
'counter_name' => 'bread',
'counter_value' => 3
],
'coin' => [
'counter_name' => 'coin',
'counter_value' => 5
]
];
return $result;
}
</pre>

'''setCounter(counter_name: stirng, new_value: string | number): void'''

updates the global this.gamedatas.counters and value of node $(counter_name)
<pre>
notif_counter: function(notif) {
this.setCounter(notif.args.counter_name, notif.args.counter_value);
},
</pre>

'''incCounter(counter_name: string, delta: number): void'''
<pre>
notif_counter : function(notif) {
this.incCounter(notif.args.counter_name, notif.args.inc);
},
</pre>

'''updateCounters(counters: object): void'''

Useful for updating game counters in the player panel (such as resources).
'counters' arg is map of counters (the key must match counter_name)
{
'bread': {
'counter_name' : 'bread',
'counter_value' => 3
},
'coin': {
'counter_name' : 'coin',
'counter_value' => 5
}
}
All counters MUST be referenced in this.gamedatas.counters (means they should be send from php) and will be updated.
DOM objects referenced by 'counter_name' will have their innerHTML updated with 'counter_value'.

Usually you call this from notification

<pre>
notif_counter : function(notif) {
this.updateCounters(notif.args.counters);
},
</pre>

== BGA GUI components ==

BGA framework provides some useful ready-to-use components for the game interface:

[[Studio#BGA_Studio_game_components_reference]]

Note that each time you are using an additional component, you must declare it at the top of your Javascript file in the list of modules used.

Example if you are using "ebg.stock":
<pre>
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/stock" /// <=== we are using ebg.stock module
],
</pre>

== BGA Buttons ==

=== Basic Button ===

'''this.addActionButton(id: string, label: string, method: string | eventhandler, destination?: string, blinking?: boolean, color?: string): void'''

You can use this method to add an action button in the main action status bar (or other places).

Arguments:
* id: an element ID that should be unique in your HTML DOM document.
* label: the text of the button. Should be translatable (use _() function). Note: this can also be any html, such as "<div class='brick'></div>", see example below on how to make image action buttons.
* method: the name of your method that must be triggered when the player clicks on this button (can be name of the method on game class or handler).
* destination (optional): id of parent on where to add button, ONLY use in rare cases if location is not action bar. Use '''null''' as value if you need to specify other arguments.
* blinking (optional): if set to '''true''', the button is going blink to catch player's attention. Please DO NOT abuse blinking button. If you need button to blink after some time passed add class 'blinking' to the button later.
* color: could be '''blue''' (default), '''red''','''gray''' or '''none'''.

You should only use this method in your "onUpdateActionButtons" method. Usually, you use it like this:

<pre>
onUpdateActionButtons: function( stateName, args ) {
if (this.isCurrentPlayerActive()) {
switch( stateName ) {
case 'giveCards':
this.addActionButton( 'giveCards_button', _('Give selected cards'), 'onGiveCards' );
this.addActionButton( 'pass_button', _('Pass'), () => this.bgaPerformAction('actPass') );
break;
}
}
},
</pre>

In the example above, we are adding a "Give selected cards" button in the case we are on game state "giveCards". When player clicks on this button, it triggers our "onGiveCards" method.

Example using blinking red button:
<pre>
this.addActionButton( 'button_confirm', _('Confirm?'), 'onConfirm', null, true, 'red');
</pre>

If you want to call the handler with arguments, you can use arrow functions, like this:
<pre>
this.addActionButton( 'commit_button', _('Confirm'), () => this.onConfirm(this.selectedCardId), null, false, 'red');
</pre>

=== Image Button ===

You can use the same method, but add extra class to a button to disable the padding and style it, i.e.
<pre>
this.addActionButton( 'button_brick', '<div class="brick"></div>', ()=>{... on brick ...}, null, null, 'gray');
dojo.addClass('button_brick','bgaimagebutton');
</pre>

where

<pre>
.bgaimagebutton {
padding: 0px 12px;
min-height: 28px;
border: none;
}
</pre>

If you use this a lot, you can define a helper function, i.e.
<pre>
/**
* This method can be used instead of addActionButton, to add a button which is an image (i.e. resource). Can be useful when player
* need to make a choice of resources or tokens.
*/
addImageActionButton: function(id, div, handler, bcolor, tooltip) {
if (typeof bcolor == "undefined") {
bcolor = "gray";
}
// this will actually make a transparent button id color = gray
this.addActionButton(id, div, handler, null, false, bcolor);
// remove border, for images it better without
dojo.style(id, "border", "none");
// but add shadow style (box-shadow, see css)
dojo.addClass(id, "shadow bgaimagebutton");
// you can also add additional styles, such as background
if (tooltip) {
dojo.attr(id, "title", tooltip);
}
return $(id);
},
</pre>

=== Disabling Button ===

You can disable the '''bgabutton''' by adding the css class '''disabled''' in you js. The disabled button is still visible but is grey and not clickable.
For example in the '''onUpdateActionButtons''' :
<pre>
this.addActionButton('play_button_id', _('Play 1 to 3 cards'), 'playFunctionButton');
if (condition) {
dojo.addClass('play_button_id', 'disabled');
}
</pre>

=== Custom Buttons ===

You can create a custom button, but the BGA framework provides a standard button that requires only .css classes: '''bgabutton''' and '''bgabutton_${color}'''.

'''Examples:'''

<pre>
<a href="#" id="my_button_id" class="bgabutton bgabutton_blue"><span>My blue button</span></a>

<a href="#" id="my_button_id" class="bgabutton bgabutton_red bgabutton_big"><span>My big red button</span></a>
</pre>

'''Note''': To see it in action, check out ''Coloretto''.

=== Button outside of action bar ===

Use addActionButton() method with destination argument set
<pre>
this.addActionButton( 'commit_button', _('Confirm'), 'onConfirm', 'player_board', true, 'red');
</pre>

in example above the button will be place on object with id 'player_board'

== Image loading ==

See also [[Game_art:_img_directory]].

'''Be careful''': by default, ALL images of your img directory are loaded on a player's browser when he loads the game. For this reason, don't let in your img directory images that are not useful, otherwise it's going to slowdown the game load.

'''this.dontPreloadImage(image_file_name: string)'''

Using dontPreloadImage, you tell the interface to not preload a specific image in your img directory.

Example of use:
<pre>
this.dontPreloadImage( 'cards.png' );
</pre>

This is particularly useful if for example you have 2 different themes for a game. To accelerate the loading of the game, you can specify to not preload images corresponding to the other theme.

Another example of use: in "Gosu" game with Kamakor extension, you play with 5 sets of cards among 10 available. Cards images are organized by sets, and we only preload the images corresponding to the 5 current sets with '''ensureSpecificGameImageLoading( image_file_names_array )'''.
<pre>
// By default, do not preload anything
this.dontPreloadImage( 'cards.png' );
this.dontPreloadImage( 'clan1.png' );
this.dontPreloadImage( 'clan2.png' );
this.dontPreloadImage( 'clan3.png' );
this.dontPreloadImage( 'clan4.png' );
this.dontPreloadImage( 'clan5.png' );
this.dontPreloadImage( 'clan6.png' );
this.dontPreloadImage( 'clan7.png' );
this.dontPreloadImage( 'clan8.png' );
this.dontPreloadImage( 'clan9.png' );
this.dontPreloadImage( 'clan10.png' );
var to_preload = [];
for( i in this.gamedatas.clans )
{
var clan_id = this.gamedatas.clans[i];
to_preload.push( 'clan'+clan_id+'.png' );
}

this.ensureSpecificGameImageLoading( to_preload );

</pre>

'''Note:''' You don't need to specify to not preload game box images (game_box.png, game_box75.png...) since they are not preloaded by default.

'''this.ensureSpecificGameImageLoading(list: string[])'''

This is oppostive of dontPreloadImage - its ensure specific images is loaded. Note: only makes sense if preload list is empty, otherwise everything is loaded anyway

'''load specific images'''
All images that will be preloaded stored in g_img_preload. If you want to override it directly - there is no API, but you can do this in GAME constructor

g_img_preload = ['tokens.png', 'trains.png', 'loc_plan.png', 'eng.png', 'eng-back.png'];

You can also set it to empty array and call ensureSpecificGameImageLoading() on specific images

== Sounds ==

Add a custom sound and make it load with your interface:

Add this in your template (.tpl) file:
<pre>
<audio id="audiosrc_<gamename>_<yoursoundname>" src="{GAMETHEMEURL}img/<gamename>_<yoursoundname>.mp3" preload="none" autobuffer></audio>
<audio id="audiosrc_o_<gamename>_<yoursoundname>" src="{GAMETHEMEURL}img/<gamename>_<yoursoundname>.ogg" preload="none" autobuffer></audio>
</pre>

Note: this is a requirement to provide both a mp3 and a ogg file with the names <code><gamename>_<yoursoundname>[.ogg][.mp3]</code>.

Play the sound (from your .js file):

<pre>
playSound('<gamename>_<yoursoundname>'); // do not add 'this.' - its a global function
</pre>

Disable the standard "move" sound for this move (to replace it with your custom sound):

Add this to your notification handler:

<pre>
this.disableNextMoveSound();
</pre>

Note: it only disable the sound for the next move.

== Title bar and states ==

=== Client states ===

Client states is a way to simulate the state transition but without actually going
to server. It is usefull when you need to ask user multiple questions before you
send things to server

'''this.setClientState(newState: string, args: object)'''

Example:
this.setClientState("client_playerPicksLocation", {
descriptionmyturn : _("${you} must select location"),
});

For more information see [[BGA_Studio_Cookbook#Multi_Step_Interactions:_Select_Worker.2FPlace_Worker_-_Using_Client_States]]

'''this.restoreServerGameState()'''
If you are in client state it will restore the current server state (cheap undo)

'''this.on_client_state'''
Boolean indicating that we are in client state

=== Title bar ===
If you simply want to show something in title bar you can do it directly
$('pagemaintitletext').innerHTML = text;

This however will not work with parameters and will not draw You in color,
if you want to do proper args rendering use method below

;'''this.removeActionButtons()'''
Removes all buttons from title bar

;'''this.updatePageTitle()'''
:This function allows to update the current page title and turn description according to the game state arguments. If the current game state description this.gamedatas.gamestate.descriptionmyturn is modified before calling this function it allows to update the turn description without changing state. This will handle arguments substitutions properly.

Note: this functional also will calls this.onUpdateActionButtons, if you want different buttons then state defaults, use method in example to replace them, if it becomes too clumsy use client states (see above)

Example from Terra Mystica:
<pre>
onClickFavorTile: function( evt ) {
...
if ( ... ) {
this.gamedatas.gamestate.descriptionmyturn = _('Special action: ') + _('Advance 1 space on a Cult track');
this.updatePageTitle();
this.removeActionButtons();
this.addActionButton( ... );
...
return;
}
...

}
</pre>

== User preferences ==
'''this.getGameUserPreference(pref_id)'''

Return the value of a user preference. It will return the value currently selected in the select combo box, in the top-right menu.

'''this.setGameUserPreference(pref_id, value)'''

Programmatically change a user preference. It will have the same effect as if the player changed the value in the select combo box, in the top-right menu.

'''this.onGameUserPreferenceChanged'''

A callback you can define if you want to be notified when a user changes a user preference.

Example:<pre>
onGameUserPreferenceChanged: function(pref_id, pref_value) {
switch (pref_id) {
case 201:
document.getElementsByTagName('html')[0].classList.toggle('dark-background', pref_value == 2);
break;
}
}
</pre>

== Other useful stuff ==

'''dojo.hitch'''

With dojo.hitch, you can create a callback function that will run with your game object context whatever happen.

Typical example: display a BGA confirmation dialog with a callback function created with dojo.hitch:

<pre>
this.confirmationDialog( _('Are you sure you want to make this?'), dojo.hitch( this, function() {
this.bgaPerformAction('makeThis');
} ) );
</pre>

In the example above, using dojo.hitch, we ensure that the "this" object will be set when the callback is called.

NOTE: In modern JS there are lambdas that eliminate need for that, the example above will look like this
<pre>
this.confirmationDialog( _('Are you sure you want to make this?'), () => this.bgaPerformAction( 'makeThis') );
</pre>

;'''onScreenWidthChange()'''
:This function can be overridden in your game to manage some resizing on the client side when the browser window is resized. This function is also triggered at load time, so it can be used to adapt to the :viewport size at the start of the game too.

; this.bRealtime
: Return true if the game is in realtime. Note that having a distinct behavior in realtime and turn-based should be exceptional.

; g_replayFrom
: Global contains replay number in live game, it is set to undefined (i.e. not set) when it is not a replay mode, so consequentially the good check is '''typeof g_replayFrom != 'undefined'''' which returns true if the game is in replay mode <i>during the game</i> (the game is ongoing but the user clicked "replay from this move" in the log)

; g_archive_mode
: Returns true if the game is in archive mode <i>after the game</i> (the game has ended)

; this.instantaneousMode
: Returns true during replay/archive mode if animations should be skipped. Only needed if you are doing custom animations. (The BGA-provided animation functions like <i>this.slideToObject()</i> automatically handle instantaneous mode.)
: Technically, when you click "replay from move #20", the system replays the game from the very beginning with moves 0 - 19 happening in instantaneous mode and moves 20+ happening in normal mode.

; g_tutorialwritten
: Returns an object like the below if the game is in tutorial mode, or undefined otherwise. Tutorial mode is a special case of archive mode where comments have been added to a previous game to teach new players the rules.
{
author: "91577332",
id: "576",
mode: "view"
status: "alpha"
version_override: null
viewer_id: "84554161"
}

'''getBgaEnvironment(): string'''
: Returns "studio" for studio and "prod" for production environment (i.e. where games current runs). Only useful for debbugging hooks.
Note: alpha server is also "prod"

[[Category:Studio]]

Game interface logic: Game.js

2024-09-25T16:38:45Z

Sguzzer Gunayer: /* Element by Id */

{{Studio_Framework_Navigation}}

__TOC__

This is the main file for your game interface. Here you will define:

* Which actions on the page will generate calls to the server.
* What happens when you get a notification for a change from the server and how it will show in the browser.
* Setup user interface

== File structure ==

The details of how the file is structured are described below with comments in the code skeleton provided to you.

Here is the basic structure:

* '''constructor''': here you can define global variables for your whole interface.
* '''setup''': this method is called when the page is refreshed, and sets up the game interface.
* '''onEnteringState''': this method is called when entering a new game state. You can use it to customize the view for each game state.
* '''onLeavingState''': this method is called when leaving a game state.
* '''onUpdateActionButtons''': called on state changes, in order to add action buttons to the status bar. Note: in a multipleactiveplayer state, it will be called when another player has become inactive.
* ''(utility methods)'': this is where you can define your utility methods.
* ''(player's actions)'': this is where you can write your handlers for player actions on the interface (example: click on an item).
* '''setupNotifications''': this method associates notifications with notification handlers. For each game notification, you can trigger a javascript method to handle it and update the game interface.
* ''(notification handlers)'': this is where you define the notifications handlers associated with notifications in '''setupNotifications''', above.

More details:

'''setup(gamedatas: object) '''
This method must set up the game user interface according to current game situation specified in parameters.
The method is called each time the game interface is displayed to a player, ie:

* when the game starts
* when a player opens a game in the browser later
* when a player refreshes the game page (F5)
* when player does a server side Undo

"gamedatas" argument contains all data retrieved by your "getAllDatas" PHP method and some more.

'''onEnteringState(stateName: string, args: { args: any } | null): void'''

This method is called each time we enter a new game state.
You can use this method to perform some user interface changes at this moment.
To access state arguments passed via calling php arg* method use args?.args.
Typically you would do something only for active player, using this.isCurrentPlayerActive() check.
It is also called (for the current game state only) when doing a browser refresh (after the setup method is called).

'''Warning''': for multipleactiveplayer states:
the active players are NOT active yet so you must use onUpdateActionButtons to perform the client side operation which depends on a player active/inactive status.
If you are doing initialization of some structures which do not depend on the active player, you can just replace (this.isCurrentPlayerActive()) with (!this.isSpectator)
for the main switch in that method.

See more details in [[Your_game_state_machine:_states.inc.php#Difference_between_Single_active_and_Multi_active_states]]

'''onLeavingState(stateName: string): void'''

This method is called each time we leave a game state.
You can use this method to perform some user interface changes at this point (i.e. cleanup).

'''onUpdateActionButtons(stateName: string, args: object | null): void'''

In this method you can manage "action buttons" that are displayed in the action status bar and highlight active UI elements.
To access state arguments passed via calling php arg* method use '''args''' parameter. Note: args can be null! For '''game''' states and when you don't supply state args function - it is null.
This method is called when the active or multiactive player changes. In a classic "activePlayer" state this method is called before the onEnteringState state.
In multipleactiveplayer state it is a mess. The sequencing of calls depends on whether you get into that state from transitions OR from reloading the whole game (i.e. F5).

See more details in [[Your_game_state_machine:_states.inc.php#Difference_between_Single_active_and_Multi_active_states]]

== Dojo framework ==

BGA uses the [http://dojotoolkit.org/ Dojo Javascript framework].

The Dojo framework allows us to do complex things more easily. The BGA framework uses Dojo extensively.

To implement a game, you only need to use a few parts of the Dojo framework. All the Dojo methods you need are described on this page.

== Javascript minimization (after July 2020) ==

For performance reasons, when deploying a game the javascript code is minimized using '''terser''' (https://github.com/terser/terser). This minifier works with modern javascript syntax. From your project "Manage game" page, you can now test a minified version of your javascript on the studio (and revert to the original).

NB: it has been reported that there is an issue with this minifier and percentage values for opacity.

== Accessing Players Information ==

'''this.player_id: number'''
id of the player who is looking at the game. The player may not be part of the game (i.e. spectator)
if (notif.args.player_id == this.player_id) {
...
}

'''this.isSpectator: boolean'''
Flag set to true if the user at the table is a spectator (not a player).

Example:
<pre>
if (this.isSpectator) {
this.player_color = 'ffffff';
} else {
this.player_color = gamedatas.players[this.player_id].color;
}
</pre>

Note: If you want to hide an element from spectators, you should use [[Game_interface_stylesheet:_yourgamename.css#spectatorMode|CSS 'spectatorMode' class]].

You may consider making a function like this, to detect if the game is in a read-only state (i.e. non-interactive):
// Returns true for spectators, instant replay (during game), archive mode (after game end)
isReadOnly: function () {
return this.isSpectator || typeof g_replayFrom != 'undefined' || g_archive_mode;
}

'''this.gamedatas: object'''
Contains the initial set of data to init the game, created at game start or by game refresh (F5).
You can update it as needed to keep an up-to-date reference of the game on the client side if you need it, however most of the time this is unnecessary.

Note: In hotseat mode, the framework does not keep this.gamedatas of hotseat players and shares the same set as the main player to store data.

Note: be careful when you update this data structurally, many framework functions expect data to be certain way and they will break if they see something else.

Typical example of accessing player's info
<pre>
for (var player_id in this.gamedatas.players) {
var playerInfo = this.gamedatas.players [player_id];
var c = playerInfo.color;
var name = playerInfo.name;
// do something
}
</pre>

'''this.isCurrentPlayerActive(): boolean'''
Returns true if the player on whose browser the code is running is currently active (it's his turn to play). Note: see remarks above about usage of this function inside onEnteringState method.
if (this.isCurrentPlayerActive()) ...

'''this.getActivePlayerId(): number'''
Return the ID of the active player, or null if we are not in an "activeplayer" type state.
if (this.player_id == this.getActivePlayerId()) ...

'''this.getActivePlayers(): number[]'''
Return an array with the IDs of players who are currently active (or an empty array if there are none).

== Accessing and manipulating the DOM ==

=== Element by Id ===

'''$(elementId: ElementOrId)'''

The $ function is used to get an HTML element using its "id" attribute.

Example: modify the content of a "span" element:

<pre>
In your HTML code:
<span id="a_value_in_the_game_interface">1234</span>

In your Javascript code:
$('a_value_in_the_game_interface').innerHTML = "9999";
</pre>

Note: It is safe to use if you don't know if variable is string (id of element) or element itself, i.e.
<pre>
foo: function(card) {
card = $(card); // now its node, no need to write if (typeof card === 'string') ...
// but its good idea to check for null here
...
}
</pre>

'''getElementById(elementId: string)'''

Note: $() is the standard method to access some HTML element with the BGA Framework. You can use '''getElementById''' but it is longer to type and less handy as it does not do some checks.

=== Style ===

'''dojo.style(node: ElementOrId, styleName: string, styleValue: any): void'''

With dojo.style you can modify the CSS property of any HTML element in your interface.

Examples:

<pre>
// Make an element disappear
dojo.style( 'my_element', 'display', 'none' );

// Give an element a 2px border
dojo.style( 'my_element', 'borderWidth', '2px' );

// Change the background position of an element
// (very practical when you are using CSS sprites to transform an element to another)
dojo.style( 'my_element', 'backgroundPosition', '-20px -50px' );
</pre>

Note: if you have to modify several CSS properties of an element, or if you have a complex CSS transformation to do, you should consider using dojo.addClass/dojo.removeClass (see below).

You can also use object to set multiple values
<pre>
dojo.setStyle("thinger", {
"opacity": 0.5,
"border": "3px solid black",
"height": "300px"
});
</pre>

'''this.addStyleToClass(cssClassName: string, styleName: string, styleValue: any):''' '''void'''

Same as dojo.style(), but for all the nodes set with the specified cssClassName
Equivalent of

dojo.query(`.${aclass}`).style(styleName, styleValue)

<pre>
dojo.query("#baz > div").style({
opacity:0.75,
fontSize:"13pt"
});
</pre>

'''Vanilla JS style'''
$('my_element').style.display='none'; // set
var display = $('my_element').style.display; // get
$('my_element').style.removeProperty('display'); // remove

=== Classes ===

'''dojo.addClass(node: ElementOrId, classes: string): void'''

'''dojo.removeClass(node: ElementOrId, classes: string): void'''

'''dojo.hasClass(node: ElementOrId, aclass: string): void'''

'''dojo.toggleClass(node: ElementOrId, aclass: string): void'''

In many situations, many small CSS property updates can be replaced by a CSS class change (i.e., you add a CSS class to your element instead of applying all modifications manually).

Advantages are:
* All your CSS stuff remains in your CSS file.
* You can add/remove a list of CSS modifications with a simple function and without error.
* You can test whether you applied the CSS to an element with the '''dojo.hasClass''' method.

Example from ''Reversi'':

<pre>
// We add "possibleMove" to an element
dojo.addClass( 'square_'+x+'_'+y, 'possibleMove' );

// In our CSS file, the class is defined as:
.possibleMove {
background-color: white;
opacity: 0.2;
filter:alpha(opacity=20); /* For IE8 and earlier */
cursor: pointer;
}

// So we've applied 4 CSS property changes in one line of code.

// ... and when we need to check if a square is a possible move on the client side:
if( dojo.hasClass( 'square_'+x+'_'+y, 'possibleMove' ) )
{ ... }

// ... and if we want to remove all possible moves in one line of code (see "dojo.query" method):
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );
</pre>

'''Vanilla JS classList'''

This is the only exception where dojo versions are better
// add class
$(token_id).classList.addClass('possibleMove');
// remove class
$(token_id).classList.removeClass('possibleMove');
// add 2 classes
const myclasses = ['a','b'];
$(token_id).classList.addClass(...myclasses);
// add classes to query result
document.querySelectorAll(".hand .card").forEach((node)=>node.classList.addClass('possibleMove'));

=== Attributes ===

;dojo.attr

With dojo.attr you can access or change the value of an attribute or property of any HTML element in your interface.

Exemple:
<pre>
// Get the title of a node
var title = dojo.attr( id, 'title' );
// Change the height of a node
dojo.attr( 'img_growing_tree', 'height', 100 );
</pre>

'''Vanilla JS attr'''

$(token).id=new_id; // set attr for "id"
var id = $(token).id; // get

=== Queries ===

'''dojo.query(cssSelector: string): Element[]'''

With dojo.query, you can query a bunch of HTML elements with a single function, with a "CSS selector" style.

Example:
<pre>
// All elements with class "possibleMove":
var elements = dojo.query( '.possibleMove' );

// Count number of tokens (i.e., elements of class "token") on the board (i.e., the element with id "board"):
dojo.query( '#board .token' ).length;
</pre>

But what is really cool with dojo.query is that you can combine it with almost all methods above.

Examples:
<pre>
// Trigger a method when the mouse enter in any element with class "meeple":
dojo.query( '.meeple' ).connect( 'onmouseenter', this, 'myMethodToTrigger' );

// Hide all meeples who are on the board
dojo.query( '#board .meeple' ).style( 'display', 'none' );
</pre>

'''Vanilla JS query'''

var cards=document.querySelectorAll(".hand .card");// all cards in all hands
var cards=$('hand').querySelectorAll(".card");// all cards in specific hand
var card=document.querySelector(".hand .card");// first card or null if none (super handy)

=== Creating and Destroying elements ===

'''dojo.empty(node: ElementOrId)'''

Remove all children of the node element
dojo.empty('my_hand');

'''dojo.destroy(node: ElementOrId)'''

Remove the element
dojo.destroy('my_token');

dojo.query(".green", mynode).forEach(dojo.destroy); // this remove all subnode of class green from mynode

'''dojo.create(tag: string, attributes?: obj, parent?: ElementOrId): Element'''

Create element

dojo.create("div", { class: "yellow_arrow" }, parent); // this creates div with class yellow_array and places it in "parent"

'''this.format_block(name: string, args: object): string'''
This bga function that takes global var from template file and substitute variables, typical use would be

var player = gamedatas.players[player_id];
var div = this.format_block('jstpl_player_board', player ); // var jstpl_player_board = ... is defined in .tpl file
Note: result is trimmed

'''this.format_string(name: string, args: object): string'''
This bga function just substitute variables in a string, i.e.
<pre>
var div = this.format_string('<div color="${player_color}"></div>', {player_color: '#ff0000'} );
</pre>
Note: result is trimmed

Note: this can be replaced by using backquoted string now:
const player_color = '#ff0000';
const div = `<div color="${player_color}"></div>`;

'''this.format_string_recursive'''
This bga function is similar to this.format_string but is capable of processing recursive argument structures and translations. It is used to format server notifications.

TODO: find better place for these function docs

=== Moving elements ===

'''dojo.place(node: string | Element, refNode: ElementOrId, pos?: string | number): Element'''

dojo.place is the best function to insert HTML code somewhere in your game interface without breaking something. It is much better to use than the '''innerHTML=''' method if you must insert HTML tags and not only values.

node:

Can be a String or a DOM node. If it is a string starting with “<”, it is assumed to be an HTML fragment, which will be created. Otherwise it is assumed to be an id of a DOM node.

<pre>
// Insert your HTML code as a child of a container element
dojo.place( "<div class='foo'></div>", "your_container_element_id" );
</pre>

pos:

Optional argument. Can be a number or one of the following strings: “before”, “after”, “replace”, “only”, “first”, or “last”. If omitted, “last” is assumed.

"replace": Replace the container element with my_node element

"first": Places the node as a child of the reference node. The node is placed as the first child.

"last" (default): Places the node as a child of the reference node. The node is placed as the last child.

"before": places the node right before the reference node.

"after": places the node right after the reference node.

"only": replaces all children of the reference node with the node.

positive integer: This parameter can be a positive integer. In this case, the node will be placed as a child of the reference node with this number (counting from 0). If the number is more than number of children, the node will be appended to the reference node making it the last child.

<pre>
// Replace all children of container with my_node
dojo.place( $('my_node'), "your_container_element_id", "only" );
</pre>

See also full doc on dojo.place: [https://dojotoolkit.org/reference-guide/1.7/dojo/place.html]

Usually, when you want to insert some piece of HTML in your game interface, you should use "[[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl#Javascript_templates|Javascript templates]]".

But you can also relocate elements like that. Note: it won't animate if you do that.

'''this.placeOnObject(mobile_obj: ElementOrId, target_obj: ElementOrId): void'''

places mobile_obj on target_obj, set the absolute positions and centers the mobile_obj on target_obj,
effect is immediate

This is not really an animation, but placeOnObject is frequently used before starting an animation.

Example:
<pre>
// (We just created an object "my_new_token")

// Place the new token on current player board
this.placeOnObject( "my_new_token", "overall_player_board_"+this.player_id );

// Then slide it to its position on the board
this.slideToObject( "my_new_token", "a_place_on_board" ).play();
</pre>

'''this.placeOnObjectPos(mobile_obj: ElementOrId, target_obj: ElementOrId, target_x: number, target_y: number): void'''

This method works exactly like placeOnObject, except than you can specify some (x,y) coordinates (in px). This way, the center of "mobile_obj" will be placed to the specified x,y position relatively to the center of "target_obj".

''Note: the placement works differently from this.slideToObjectPos'', since coordinates are calculated based on the center of objects.

'''this.attachToNewParent(mobile_obj: ElementOrId, target_obj: ElementOrId): void'''

With this method, you change the HTML parent of "mobile_obj" element without moving it.
"target_obj" is the new parent of this element. The beauty of
attachToNewParent is that the mobile_obj element DOES NOT MOVE during this process.

What happens is that the method calculate a relative position of mobile_obj to make sure it does not move after the HTML parent changes.

Why using this method?

Changing the HTML parent of an element can be useful for the following reasons:
* When the HTML parent moves, all its child are moving with them. If some game elements is no more linked with a parent HTML object, you may want to attach it to another place.
* The z_order (vertical order of display) depends on the position in the DOM, so you may need to change the parent of some game elements when they are moving in your game area.

'''CAREFUL''': this function destroys original object and places a clone onto a new parent, this will break all references to this HTML element (ex: dojo.connect).
If you need version that does not destroy the object but the same otherwise see [[BGA_Studio_Cookbook#Attach_to_new_parent_without_destroying_the_object]]

== Animations ==

===Dojo Animations===

BGA animations is based on Dojo Animation ([http://dojotoolkit.org/documentation/tutorials/1.8/animation/ see tutorial here]).

However, most of the time, you can just use methods below, which are built on top of Dojo Animation.

Note: one interesting method from Dojo that could be useful from time to time is "Dojo.Animation". It allows you to make any CSS property "slide" from one value to another.

Note 2: the slideTo methods are not compatible with CSS transform (scale, zoom, rotate...). If possible, avoid using CSS transform on nodes that are being slided. Eventually, the only possible solution to make these 2 compatible is to disable all CSS transform properties, use slideToObjectPos/placeOnObjectPos, and then apply them again.

===Sliding===

'''this.slideToObject(mobile_obj: ElementOrId, target_obj: ElementOrId, duration?: number, delay?: number): Animation'''

You can use slideToObject to "slide" an element to a target position.

Sliding element on the game area is the recommended and the most used way to animate your game interface. Using slides allow players to figure out what is happening on the game, as if they were playing with the real boardgame.

The parameters are:
* mobile_obj: the ID of the object to move. This object must be "relative" or "absolute" positioned.
* target_obj: the ID of the target object. This object must be "relative" or "absolute" positioned. Note that it is not mandatory that mobile_obj and target_obj have the same size. If their size are different, the system slides the center of mobile_obj to the center of target_obj.
* duration: (optional) defines the duration in millisecond of the slide. The default is 500 milliseconds.
* delay: (optional). If you defines a delay, the slide will start only after this delay. This is particularly useful when you want to slide several object from the same position to the same position: you can give a 0ms delay to the first object, a 100ms delay to the second one, a 200ms delay to the third one, ... this way they won't be superposed during the slide.

BE CAREFUL: The method returns an dojo.fx animation, so you can combine it with other animation if you want to. It means that you have to call the "play()" method, otherwise the animation WON'T START.

Example:
<pre>
this.slideToObject( "some_token", "some_place_on_board" ).play();
</pre>

'''this.slideToObjectPos(mobile_obj: ElementOrId, target_obj: ElementOrId, target_x: number, target_y: number, duration?: number, delay?: number): Animation'''

This method does exactly the same as "slideToObject", except than you can specify some (x,y) coordinates. This way, "mobile_obj" will slide to the specified x,y position relatively to "target_obj".

Example: slide a token to some place on the board, 10 pixels from the top:
<pre>
this.slideToObjectPos( "some_token", "some_place_on_board", 0, 10 ).play();
</pre>

'''this.slideTemporaryObject(mobile_obj_html: string, parent: ElementOrId, from: ElementOrId, to: ElementOrId, duration?: number, delay?: number): Animation'''

This method is useful when you want to slide a temporary HTML object from one place to another. As this object does not exists before the animation and won't remain after, it could be complex to create this object (with dojo.place), to place it at its origin (with placeOnObject) to slide it (with slideToObject) and to make it disappear at the end.

slideTemporaryObject does all of this for you:
* mobile_obj_html is a piece of HTML code that represent the object to slide.
* parent is the ID of an HTML element of your interface that will be the parent of this temporary HTML object.
* from is the ID of the origin of the slide.
* to is the ID of the target of the slide.
* duration/delay works exactly like in "slideToObject"

Example:
<pre>
this.slideTemporaryObject( '<div class="token_icon"></div>', 'tokens', 'my_origin_div', 'my_target_div' ).play();
</pre>

===Destroy===
'''this.slideToObjectAndDestroy(mobile_obj: ElementOrId, target_obj: ElementOrId, duration?: number, delay?: number): void'''

This method is a handy shortcut to slide an existing HTML object to some place then destroy it upon arrival. It can be used for example to move a victory token or a card from the board to the player panel to show that the player earns it, then destroy it when we don't need to keep it visible on the player panel.

It works the same as this.slideToObject and takes the same arguments, but it starts the animation.

CAREFUL: Make sure nothing is creating the same object at the same time the animation is running, because this will cause some random disappearing effects

Example:
<pre>
this.slideToObjectAndDestroy( "some_token", "some_place_on_board", 1000, 0 );
</pre>

'''this.fadeOutAndDestroy( node: string | Element, duration?: number, delay?: number):''' '''void'''

This function fade out the target node, then destroy it. Its starts the animation.
* duration/delay works exactly like in "slideToObject"

Example:
<pre>
this.fadeOutAndDestroy( "a_card_that_must_disappear" );
</pre>

CAREFUL: the HTML node still exists until during few milliseconds, until the fadeOut has been completed.
Make sure nothing is creating same object at the same time as animation is running, because you will be some random dissapearing effects

===Rotating elements===

This example combines "Dojo.Animation" method and a CSS property transform that allow you to rotate the element.
<pre>
// node is Element we rotating
var animation = new dojo.Animation({
curve: [fromDegree, toDegree],
onAnimate: (v) => {
node.style.transform = 'rotate(' + v + 'deg)';
}
});

animation.play();
</pre>

BGA has its own interface to rotate

'''this.rotateTo(node: string | Element, degree: number): void'''

It starts the animation, and stored the rotation degree in the class, so next time you rotate object - it is additive.
There is no animation hooks in this one, if you need to change any parameters use dojo animation above.

There is also '''rotateInstantTo''' with same signature which does not animate

===Animation Callbacks===

If you wish to run some code only after an animation has completed you can do this by linking a callback method to 'onEnd'.

<pre>
var animation_id = this.slideToObject( mobile_obj, target_obj, 500 );
dojo.connect(animation_id, 'onEnd', () => {
// do something here
});
animation_id.play();
</pre>

If you wish to call a second animation after the first (rather than general code) then you can use a dojo animation chain (see tutorial referenced above).

== Players input ==

=== Connecting ===
'''dojo.connect(element: Element, event: string, context: object, method: eventHandler): any'''

'''dojo.connect(element: Element, event: string, hander: eventHandler): any'''

Used to associate a player event with one of your notification methods.

Example: associate a click on an element ("my_element") with one of our methods ("onClickOnMyElement"):
<pre>
dojo.connect( $('my_element'), 'onclick', this, 'onClickOnMyElement' );
</pre>

Same idea but base on query (i.e. all element of 'pet' class)
dojo.query(".pet").connect('onclick', this, 'onPet');

Note: if you need to disconnect the handler you have to store handler returned from this method, i.e.

<pre>
var handler = dojo.connect(...);
...
dojo.disconnect(handler);
</pre>

If you don't store the handler - you have to destroy the object to disconnect it

Typical function that implements the input handler will look like this

<pre>
onPet: function(event) {
var id = event.currentTarget.id;
console.log('onPet ' + id);
dojo.stopEvent(event);
if (this.gamedatas.gamestate.name == 'playerTurnPet') {
this.bgaPerformAction('actPlayPet', {card: id});
} else {
this.showMoveUnauthorized();
}
}
</pre>

'''this.connect(element: ElementOrId, event: string, method: eventHandler): void'''

Used to associate a player event with one of your notification methods.

this.connect( $('my_element'), 'onclick', 'onClickOnMyElement' );

Or you can use an in-place handler

this.connect( $('my_element'), 'onclick', (e) => { console.log('boo'); } );

Note that this function stores the connection handler. That is the only real difference between '''this.connect''' and '''dojo.connect'''. If you plan to destroy the element you connected, you '''must''' call this.disconnect() to prevent memory leaks.
This function is mainly for permanent objects - if you just want to connect the temp object you should probably not use this method but use dojo.connect which won't require any clean-up.

'''this.connectClass(cssClassName: string, event: string, method: eventHandler): void'''

Same as connect(), but for all the nodes set with the specified cssClassName.

this.connectClass('pet', 'onclick', 'onPet');

'''this.disconnect(element: ElementOrId, event: string): void'''

Disconnect event handler (previously registered with this.connect or this.connectClass).

this.disconnect( $('my_element'), 'onclick');

Note: dynamic connect/disconnect is for advanced cases ONLY, you should always connect elements statically if possible, i.e. in setup() method.

'''this.disconnectAll(): void'''

Disconnect all previously registed event handlers (registered via this.connect or this.connectClass)

this.disconnectAll();

=== Actions ===

'''this.bgaPerformAction(action: string, args?: object, options: object = { lock: true, checkAction: true }): Promise<void>'''

Triggers an action on the backend. This is a combination of checkAction and ajaxcall, returning a Promise which resoves when ajaxcall ends.

This method must be used to send a player input to the game server. '''It should not be triggered programmatically''', especially not in loops, in callbacks, in notifications, or in onEnteringState/onUpdateActionButtons/onLeavingState, in order not to create race conditions or break replay game and tutorial features. It should be used only in reaction to a user action in the interface.

* action: name of the action, as it is written in "possibleactions" of the current state.
* args: an object containing the call parameters to send to the action
* options: options to tweak the call with some defaults. Default is <code>{ lock: true, checkAction: true }</code>.

Example of a standard call without args:
this.bgaPerformAction('pass');

Example of a standard call with action args:
this.bgaPerformAction('actPlayCard', { id: this.selectedCardId });

Example of a call without checking action (because player is inactive in a multiactive state):

this.bgaPerformAction('actChangeMind', {}, { checkAction: false });

Example of a call without lock (because of a special action not directly related to the game flow):

this.bgaPerformAction('actSetAutoBid', { alwaysBidUntil: 500 }, { lock: false, checkAction: false });

Example of call with reaction to exception:
this.bgaPerformAction('actPlayCard', { id: this.selectedCardId }).catch(()=>{ this.selectedCardId = undefined; });

Example of call with reaction to success:
this.bgaPerformAction('actPlayCard', { id: this.selectedCardId }).then(()=>{ this.unselectAll(); });

'''this.ajaxcall(url, parameters, obj_callback, callback, callback_anycase?, ajax_method?: string)'''

''Note: bgaPerformAction is a simpler way to use ajax calls, ajaxcall stays in the doc for legacy reasons only and should not be used in new projects.''

Same warning as '''this.bgaPerformAction''' about using on user action only.

* url: the url of the action to perform. For a game, it must be: "/<mygame>/<mygame>/myAction.html"
* parameters: an array of parameter to send to the game server.
** Note that "lock: true" must always be specified in this list of parameters in order the interface can be locked during the server call. Cannot use lock: false - to not lock it has to be undefined.
** Note: Restricted parameter names (please don't use them):
*** "action"
*** "module"
*** "class"
* obj_callback: must be set to "this".
* callback (non-optional but rarely used): a function to trigger when the server returns result and everything went fine (not used, as all data handling is done via notifications).
* callback_anycase: (optional) a function to trigger when the server returns ok OR error. If no error this function is called with parameter value false. If an error occurred, the first parameter will be set to true, the second will contain the error message sent by the PHP back-end, and the third will contain an error code.
* ajax_method: (optional and rarely used) if you need to send large amounts of data (over 2048 bytes), you can set this parameter to 'post' (all lower-case) to send a POST request as opposed to the default GET. This works, but was not officially documented, so only use if you really need to.

Usage:
<pre>
this.ajaxcall( '/mygame/mygame/actMyAction.html', { lock: true,
arg1: myarg1,
arg2: myarg2
}, this, (result)=>{} );
</pre>

'''this.checkAction(action: string, nomessage?: boolean): boolean '''

Check if player can do the specified action by taking into account:
* if interface is locked it will return false and show message "An action is already in progress", unless nomessage set to true
* if player is not active it will return false and show message "This is not your turn", unless nomessage set to true
* if action is not in list in possible actions (defined by "possibleaction" in current game state) it will return false and show "This move is not authorized now" error (unconditionally).
* otherwise returns true
Example:
<pre>
function onClickOnGameElement( evt ) {
if( this.checkAction( "actMyAction" ) ) {
// Do the action
}
}
</pre>

'''this.checkPossibleActions(action: string): boolean'''

* this is independent of the player being active, so can be used instead of this.checkAction(). This is particularly useful for multiplayer states when the player is not active in a 'player may like to change their mind' scenario. Unlike this.checkAction, this function does NOT take interface locking into account

* if action is not in list in possible actions (defined by "possibleaction" in current game state) it will return false and show "This move is not authorized now" error (unconditionally).
* otherwise returns true

function onChangeMyMind( evt ) {
if( this.checkPossibleActions( "actMyAction" ) ) {
// Do the action
}
}

'''this.checkLock(nomessage?: boolean): boolean'''

When using "lock: true" in ajax call you can use this function to check if interface is in lock state (it will be locked during server call and notification processing).
This check can be used to block some other interactions which do not result in ajaxcall or if you want to suppress errors. Note: normally you only need to use this.checkAction(...), this is for advanced cases.

It will also show error unless nomessage is set to true

function onChangeMyMind( evt ) {
if( this.checkLock() ) {
// Do the action
}
}

== Notifications ==

When something happens on the server side, your game interface Javascript logic received a notification.
If you have not done so yet check what notification are in [[Main_game_logic:_yourgamename.game.php#Notifications]]

Here's how you can handle these notifications on the client side.

=== Subscribe to notifications ===

'''dojo.subscribe(notif_type: string, callback_obj: Object, handler: string|handler)'''
* notif_type - notification type/name send by php server
* callback_obj - usually this
* handler - if string method of callback_obj with name name is called, when notification is called, with notification object as parameter (see below)

Your Javascript "setupNotifications" method is the place where you can subscribe to notifications from your PHP code.

Here's how you associate one of your Javascript method to a notification "playDisc" (from Reversi example):

<pre>
setupNotifications: function() {
...
dojo.subscribe('playDisc', this, "notif_playDisc");
},
</pre>

Note: the "playDisc" corresponds to the name of the notification you define it in your PHP code, in your "notifyAllPlayers" or "notifyPlayer" method.

Then, you have to define your "notif_playDisc" method:

<pre>
notif_playDisc: function(notif) {
// Remove current possible moves (makes the board more clear)
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );
this.addDiscOnBoard( notif.args.x, notif.args.y, notif.args.player_id );
},
</pre>

In a notification handler like our "notif_playDisc" method, you can access all notifications arguments with "notif.args".

Example:

PHP

<pre>
$this->notifyAllPlayers( "apples", clienttranslate('player takes ${count} apples'), [ "count" => 3 ] );
</pre>

JavaScript

<pre>
setupNotifications: function() {
dojo.subscribe( 'apples', this, 'notif_apples' );
},

notif_apples: function(notif) {
//You can access the "count" like this:
alert("count = " + notif.args.count);
}
</pre>

=== The notification Object received by client ===

When sending a notification on your PHP, the client side will receive an Object with the following attributes:

* type - type of the notification (as passed by php function)
* log - the log string passed from php notification
* args - This is the arguments that you passed on your notification method on php
* bIsTableMsg - is true when you use [[Main_game_logic:_yourgamename.game.php#NotifyAllPlayers|NotifyAllPlayers]] method (false otherwise)
* channelorig - information about table ID (formatted as : "/table/t[TABLE_NUMBER]")
* gamenameorig - name of the game
* move_id - ID of the move associated with the notification
* table_id - ID of the table (comes as string)
* time - UNIX GMT timestamp
* uid - unique identifier of the notification
* h - unknown

'' Note that those information were inferred from observation on console log. If an Admin can confirm/correct (and remove this line), you're welcome :)''

=== Ignoring notifications ===

Sometimes you need to ignore some notification on client side. You don't want them to be shown in game log and you don't want them to be handled.

The most common use case is when a player gets private information. They will receive a specific notification (such as "You received Ace of Heart"), while other players would receive more generic notification ("Player received a card").

In X.game.php
<pre>
$this->notifyAllPlayers("dealCard", clienttranslate('${player_name} received a card'), [
'player_id' => $playerId,
'player_name' => $this->getActivePlayerName()
]);

$this->notifyPlayer($playerId, "dealCardPrivate", clienttranslate('You received ${cardName}'), [
"type" => $card["type"],
"cardName" => $this->getCardName($card["type"])
]);
</pre>

The problem with this approach is that the active player will receive two notifications:
* Player1 received a card
* You received Ace of Hearts

Hence, notification ignoring.

NOTE: You can think that it would be possible to send such notification to all players except active just by using notifyPlayer and it seems to work. The problem however is that table spectators would miss such notification and their user interface (and game log) wouldn't be updated. Since there is no way to send notification just to spectators, ignoring the notification (or "filtering") is the only reasonable solution.

'''setIgnoreNotificationCheck(notif_type: string, predicate: ((notif: Notif)=>boolean))'''
This method will set a check whether any of notifications of specific type should be ignored.

The parameters are:
* notif_type: type of the notification
* predicate (notif => boolean): a function that will receive notif object and will return true if this specific notification should be ignored

Before dispatching any notification of this type, the framework will call predicate to check whether notification should be ignored, if it return true - the notification will be dispatched, i.e. logged or handled.

<pre>
this.notifqueue.setIgnoreNotificationCheck( 'dealCard', (notif) => (notif.args.player_id == this.player_id) );
</pre>

IMPORTANT: Remember that this notification is ignored on the client side, but was still received by the client. Therefore it shouldn't contain any private information as cheaters can get it. In other words this is not a way to hide information.

IMPORTANT: When a game is reloaded with F5 or when opening a turn based game, old notifications are replayed as history notification. They are used just to update the game log and are stripped of all arguments except player_id, i18n and any argument present in message. If you use and other argument in your predicate you should '''preserve''' it as explained [[Main_game_logic:_yourgamename.game.php#Notify_players|here]].

=== Synchronous notifications ===

When several notifications are received by your game interface, these notifications are processed immediately, one after the other, in the same exact order they have been generated in your PHP game logic.

However, sometimes, you need to give some time to the players to figure out what happened on the game before jumping to the next notification. Indeed, in many games, there are a lot of automatic actions, and the computer is going to resolve all these actions very fast if you don't tell it not to do so.

As an example, for Reversi, when someone is playing a disc, we want to wait 500 milliseconds before doing anything else in order the opponent player can figure out what move has been played.

Here's how we do this, right after our subscription:
<pre>
dojo.subscribe( 'playDisc', this, "notif_playDisc" );
this.notifqueue.setSynchronous( 'playDisc', 500 ); // Wait 500 milliseconds after executing the playDisc handler
</pre>

-----

It is also possible to control the delay timing dynamically (e.g., using notification args). As an example, maybe your notification 'cardPlayed' should pause for a different amount of time depending on the number or type of cards played.

For this case, use '''setSynchronous''' without specifying the duration and use '''setSynchronousDuration''' within the notification callback.

* NOTE: If you forget to invoke '''setSynchronousDuration''', the game will remain paused forever!

<pre>
setupNotifications: function () {
dojo.subscribe( 'cardPlayed', this, 'notif_cardPlayed' );
this.notifqueue.setSynchronous( 'cardPlayed' ); // wait time is dynamic
...
},

notif_cardPlayed: function (notif) {
// MUST call setSynchronousDuration

// Example 1: From notification args (PHP)
this.notifqueue.setSynchronousDuration(notif.args.duration);
...

// Or, example 2: Match the duration to a Dojo animation
var anim = dojo.fx.combine([
...
]);
anim.play();
this.notifqueue.setSynchronousDuration(anim.duration);
},
</pre>

You can also manually call this.notifqueue.setSynchronousDuration(0) once client operations are finished, but be careful that even fast replay still has a path to call it.

'''WARNING: combining synchronous and ignored notifications'''
You must be careful when combining dynamic synchronous durations (as described above) with ignored notifications. If you have a conditionally ignored notification like this (see below section):

<pre>this.notifqueue.setIgnoreNotificationCheck( 'myNotif', (notif) => (notif.args.player_id == this.player_id) /* or any other condition */ )</pre>

then you CANNOT do

<pre>this.notifqueue.setSynchronous('myNotif');</pre>

as, when the ignored check passes, the notification handler, in which `this.notifqueue.setSychronousDuration` is called, is never called and so the duration is never set and interface locking results.

The workaround is to set a "dummy" time:

<pre>this.notifqueue.setSynchronous('myNotif', 5000);</pre>

whose value is irrelevant but must be large enough to cover the time before the notification handler is called. The large value never actually comes into play because the notification is either ignored, or the synchronous duration is reset to a sensible value inside the handler.

=== Pre-defined notification types ===

'''tableWindow''' - This defines notification to display [[Game_interface_logic:_yourgamename.js#Scoring_dialogs|Scoring Dialogs]], see below.

'''message''' - This defines notification that shows on players log and have no other effect (technically any unhandled notification will do the same but its recommended to use this keyword for consistency)

// You can call this on php side without doing anything on client side
self::notifyAllPlayers( 'message', clienttranslate('hello'), [] );

'''simplePause''' - This notification will just delay other notifications, maybe useful if you know you need some extra time for animation or something. Requires a time parameter.

<pre>
self::notifyAllPlayers( 'simplePause', '', [ 'time' => 500] ); // time is in milliseconds
</pre>

Note: the following types are RESERVED by framework, do not use:

gameStateChange gameStateChangePrivateArg gameStateMultipleActiveUpdate newActivePlayer playerstatus yourturnack clockalert tableInfosChanged playerEliminated tableDecision archivewaitingdelay end_archivewaitingdelay replaywaitingdelay end_replaywaitingdelay replayinitialwaitingdelay end_replayinitialwaitingdelay aiPlayerWaitingDelay replay_has_ended updateSpectatorList wouldlikethink updateReflexionTime undoRestorePoint resetInterfaceWithAllDatas zombieModeFail zombieModeFailWarning aiError skipTurnOfPlayer zombieBack allPlayersAreZombie gameResultNeutralized playerConcedeGame showTutorial showCursor showCursorClick skipTurnOfPlayerWarning banFromTable resultsAvailable switchToTurnbased newPrivateState infomsg

== Tooltips ==

=== Adding static tooltips ===

'''this.addTooltip(nodeId: string, helpStringTranslated: string, actionStringTranslated: string, delay?: number): void'''

Add a simple text tooltip to the DOM node.

Specify 'helpStringTranslated' to display some information about "what is this game element?".
Specify 'actionStringTranslated' to display some information about "what happens when I click on this element?".

You must specify both of the strings. You can only use one and specify an empty string ('') for the other one.

When you pass text directly function _() must be used for the text to be marked for translation! Except for empty string.

Parameter "delay" is optional. It is primarily used to specify a zero delay for some game element when the tooltip gives really important information for the game - but remember: no essential information must be placed in tooltips as they won't be displayed in some browsers (see [[BGA_Studio_Guidelines|Guidelines]]).

Example:
<pre>
this.addTooltip( 'cardcount', _('Number of cards in hand'), '' );
</pre>

Note: this generates static tooltip and attaches to existing dom element, if you need to generate tooltip more dynamically you have to call that method every time information about object is updated or use completely different tehnique, see dynamic tooltips below.

'''this.addTooltipHtml(nodeId: string, html: string, delay?: number): void'''

Add an HTML tooltip to the DOM node (for more elaborate content such as presenting a bigger version of a card).

'''this.addTooltipToClass(cssClass: string, helpStringTranslated: string, actionStringTranslated: string, delay?: number ): void'''

Add a simple text tooltip to all the DOM nodes set with this cssClass. See more details above for this.addTooltip.
this.addTooltipToClass( 'meeple', _('This is A Meeple'), _('Click to tickle') );

IMPORTANT: all concerned nodes must exist and have IDs to get tooltips.

'''this.addTooltipHtmlToClass(cssClass: string, html: string, delay?: number): void'''

Add an HTML tooltip to to all the DOM nodes set with this cssClass (for more elaborate content such as presenting a bigger version of a card).

IMPORTANT: all concerned nodes must exist and have IDs to get tooltips.

=== Removing static tooltips ===

'''this.removeTooltip(nodeId: string): void'''

Remove a tooltip from the DOM node with given id.

=== Advanced tooltips ===

'''force tooltip to open'''

If you want to force tooltip to open in reaction to some other action, i.e. click you can do this

this.tooltips[id].open(id)

where id is the id of the tooltip node where tooltip was installed.

'''dynamic tooltips'''

See [[BGA_Studio_Cookbook#Dynamic_tooltips]]

'''tooltips on mobile'''

Tooltips is very unreliable on mobile, it is recommended to implement some other method to obtaining same information,
such as simple click handler in dedicated "Help" mode or provide dedicated clickable areas such as corner of card.

== Warning messages ==

Sometimes, there is something important that is happening in the game and you have to make sure all players get the message. Most of the time, the evolution of the game situation or the game log is enough, but sometimes you need something more visible.

Ex: someone fulfills one of the end of the game conditions, so this is the last turn.

'''this.showMessage(msg: string, type: string): void'''

showMessage shows a message in a big rectangular area on the top of the screen of the current player, and it dissapears after few seconds (also it will be in the log in some cases).

* "msg" is the string to display. It should be translated.
* "type" can be set to "info", "error", "only_to_log" or custom string. If set to "info", the message will be an informative message on a white background. If set to "error", the message will be an error message on a red background and it will be added to log. If set to "only_to_log", the message will be added to the game log but will not popup at the top of the screen.
If set to custom string, it will be transparent, to use custom type define "head_xxx" in css, where xxx is the type. For example if you want yellow warning, use "warning" as type and add this to css:
.head_warning {
background-color: #e6c66e;
}

Important: the normal way to inform players about the progression of the game is the game log. The "showMessage" is intrusive and should not be used often.

<pre>
notif_messageinfo: function(notif) {
if (!g_archive_mode) {
var message = this.format_string_recursive(notif.log, notif.args);
this.showMessage(_('Announcement:') + " " + message, 'info');
}
},
</pre>

Show message could be used on the client side to prevent user wrong moves before it is send to server.
Example from 'battleship':
<pre>
onGrid: function(event) {
if (checkIfPlayerTriesToFireOnThemselves(event)) {
this.showMessage(_('This is your own board silly!'), 'error');
return;
}
...
},
</pre>

'''this.showMoveUnauthorized(): void'''

Shows predefined user error that move is unauthorized now

<pre>
onPet: function(event) {
if (checkPet(event)==false) {
this.showMoveUnauthorized();
return;
}
...
},
</pre>

== Dialogs ==

=== Confirmation dialog ===

When an important action with a lot of consequences is triggered by the player, you may want to propose a confirmation dialog.

CAREFUL: the general guideline of BGA is to AVOID the use of confirmation dialogs. Confirmation dialogs slow down the game and bother players. The players know that they have to pay attention to each move when they are playing online.

The situations where you should use a confirmation dialog are the following:
* It must not happen very often during a game.
* It must be linked to an action that can really "kill a game" if the player does not pay attention.
* It must be something that can be done by mistake (ex: a link on the action status bar).

'''this.confirmationDialog(message: string, yesHandler: (param: any) => void, noHandler?: (param: any) => void, param?: any): void'''

* message - message will be shown to user, use _() to translate
* yesHandler - non-optional handler to be called on yes
* noHandler - optional handler to called on no
* param - if specified, it will be passed to both handlers
NOTE: this is async function, it does not return anything and you should not do anything after, you must do everything in handlers

How to display a confirmation dialog:
<pre>
this.confirmationDialog(_("Are you sure you want to bake a pie?"), () => {
this.bakeThePie();
});
return; // nothing should be called or done after calling this, all action must be done in the handler
</pre>
With param and both handlers
<pre>
this.confirmationDialog(_("Are you sure you want to bake a pie?"),
(ingredient) => this.bakeThePie(ingredient),
(ingredient) => console.log(`cancelled baking of ${ingredient}`),
'apple');
</pre>

=== Multiple choice dialog ===

You can use this dialog to give user a choice with small amount of options

'''this.multipleChoiceDialog(message: string, choices: string[], callback: (choice: number) => void): void'''
* message - message will be shown to user, use _() to translate
* choices - array of choices
* callback - non-optional handler to be called on choice made, the choice parameter is the INDEX of the choice from the array of choices

NOTE: this is async function, it does not return anything and you should not do anything after, you must do everything in handlers
NOTE: there is no cancel handler, so make sure you gave user a choice to get out of it

Example:
<pre>
const keys = ["0", "1", "5", "10"];
this.multipleChoiceDialog(_("How many bugs to fix?"), keys, (choice) => {
if (choice==0) return; // cancel operation, do not call server action
var bugchoice = keys[choice]; // choice will be 0,1,2,3 here
this.bgaPerformAction("fixBugs", { number: bugchoice });
});
return; // must return here
</pre>

=== Generic Dialogs ===

As a general rule, you shouldn't use dialogs windows.

BGA guidelines specify that all game elements should be displayed on the main screen. Players can eventually scroll down to see game elements they don't need to see anytime, and you may eventually create anchors to move between game area section. Of course dialogs windows are very practical, but the thing is: all players know how to scroll down, and not all players know how to show up your dialog window. In addition, when the dialog shows up, players can't access the other game components.

Sometimes although, you need to display a dialog window. Here is how you do this:

// Create the new dialog over the play zone. You should store the handler in a member variable to access it later
this.myDlg = new ebg.popindialog();
this.myDlg.create( 'myDialogUniqueId' );
this.myDlg.setTitle( _("my dialog title to translate") );
this.myDlg.setMaxWidth( 500 ); // Optional

// Create the HTML of my dialog.
// The best practice here is to use [[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl#Javascript_templates|Javascript templates]]
var html = this.format_block( 'jstpl_myDialogTemplate', {
arg1: myArg1,
arg2: myArg2,
...
} );

// Show the dialog
this.myDlg.setContent( html ); // Must be set before calling show() so that the size of the content is defined before positioning the dialog
this.myDlg.show();

// Now that the dialog has been displayed, you can connect your method to some dialog elements
// Example, if you have an "OK" button in the HTML of your dialog:
dojo.connect($('my_ok_button'), 'onclick', this, (event) => {
event.preventDefault();
this.myDlg.destroy();
});

If necessary, you can remove the default top right corner 'close' icon, or replace the function called when it is clicked:
// Removes the default close icon
this.myDlg.hideCloseIcon();

// Replace the function call when it's clicked
this.myDlg.replaceCloseCallback((event) => { ... });

=== Scoring dialogs ===

Sometimes at the end of a round you want to display a big table that details the points wins in each section of the game.

Example: in Hearts game, we display at the end of each round the number of "heart" cards collected by each player, the player who collected the Queen of Spades, and the total number of points loose by each player.

Scoring dialogs are managed entirely on '''PHP side''', but they are described here as their effects are visible only on client side.

Displaying a scoring dialog is quite simple and is using a special notification type: "tableWindow":
<pre>
// on PHP side:
$this->notifyAllPlayers( "tableWindow", '', array(
"id" => 'finalScoring',
"title" => clienttranslate("Title of the scoring dialog"),
"table" => $table
));
</pre>

The "table" argument is a 2 dimensional PHP array that describes the table you want to display, line by line and column by column.

Example: display an 3x3 array of strings
<pre>
$table = [
[ "one", "two", "three" ], // This is my first line
[ "four", "five", "six" ], // This is my second line
[ "seven", "height", "nine" ] // This is my third line
];
</pre>

As you can see above, in each "cell" of your array you can display a simple string value. But you can also display a complex value with a template and associated arguments like this:
<pre>
$table = [
[ "one", "two", [ "str" => clienttranslate("a string with an ${argument}"), "args" => [ 'argument' => 'argument_value' ] ] ],
[ "four", "five", "six" ],
[ "seven", "height", "nine" ]
];
</pre>

This is especially useful when you want to display player names with colors. Example from "Hearts":
<pre>
$firstRow = [ '' ];
foreach( $players as $player_id => $player ) {
$cell = [ 'str' => '${player_name}',
'args' => [ 'player_name' => $player['player_name'] ],
'type' => 'header'
];
$firstRow[] = $cell;
}
$table[] = $firstRow;
...
</pre>

You can also use three extra attributes in the parameter array for the notification:
* '''header''': the content for this parameter displays before the table (also, the html will be parsed and player names will be colored according to the current game colors).
* '''footer''': the content for this parameter displays after the table (no parsing for coloring the player names)
* '''closing''': if this parameter is used, a button will be displayed with this label at the bottom of the popup and will allow players to close it (more easily than by clicking the top right 'cross' icon).

<pre>
$this->notifyAllPlayers( "tableWindow", '', [
"id" => 'finalScoring',
"title" => clienttranslate("Title of the scoring dialog"),
"table" => $table,
"header" => ['str' => clienttranslate('Table header with parameter ${number}'),
'args' => [ 'number' => 3 ],
],
"footer" => '<div class="myfoot"></div>',
"closing" => clienttranslate( "Closing button label" )
] );
</pre>

Note: currently id is not used - so you cannot access resulting div by id on js side
Note: any traslatable stirng have to be wrapped by clienttranslate() on top level OR it has to be recursive template.

DO NOT DO THIS:
<pre>
"footer" => '<div>'.clienttranslate( "The end" ).'</div>', // this will not work for translations!!!
</pre>

=== Scoring animated display ===

Sometimes, you may want to display a score value over an element to make the scoring easier to follow for the players (Terra Mystica final scoring for example).
You can do it with:

'''this.displayScoring(anchor_id: string, color: string, score: number | string, duration?: number, offset_x?: number, offset_y?: number): void'''

'''anchor_id''': ID of the html element to place the animated score onto (without the '#')

'''color''': hexadecimal RGB representation of the color (should be the color of the scoring player), but without a leading '#'. For instance, 'ff0000' for red.

'''score''': numeric score to display, prefixed by a '+' or '-'

'''duration''': animation duration in milliseconds (optional, default is 1000)

'''offset_x''' and '''offset_y''': if both offset_x and offset_y are defined and not null, apply the following offset (in pixels) to the scoring animation.
Note that the score is centered in the anchor, so the offsets might have to be negative if you calculate the position.

Note: if you want to display successively each score, you can use ''this.notifqueue.setSynchronous()'' function.
<pre>
setupNotifications: function() {
dojo.subscribe( 'displayScoring', this, "notif_displayScoring" );
...
}
...

notif_displayScoring: function(notif) {
const duration = notif.args.duration?notif.args.duration:1000;
this.notifqueue.setSynchronous('displayScoring', duration );
this.displayScoring( notif.args.target, notif.args.color, notif.args.score, duration);
},
</pre>

=== Speech bubble ===

For better interactivity in some games (Love Letter for example), you may use comic book style speech bubbles to express the players voices.
This is done with showBubble:

'''this.showBubble(anchor_id: string, text: string, delay?: number, duration?: number, custom_class?: string): void'''

* anchor_id - where to attach the bubble
* text - what to put in bubble, can be html
* delay - delay in milliseconds (optional, default 0)
* duration - duration of animation in milliseconds (optional, default 3000)
* custom_class - extra class to add to bubble (optional), if you need to override the default bubble style

<pre>
this.showBubble('meeple_2', _('Hello'), 0, 1000, 'pink_bubble');
</pre>

<pre>
notif_speechBubble(notif) {
var html = this.format_string_recursive(notif.args.text, notif.args.args);
this.showBubble(notif.args.target, html, notif.args.delay ?? 0, notif.args.duration ?? 1000);
},
</pre>

'''Warning''': if your bubble could overlap other active elements of the interface (buttons in particular), as it stays in place even after disappearing, you should use a custom class to give it the style "pointer-events: none;" in order to intercept click events.

Note: If you want this visually, but want to take complete control over this bubble and its animation (for example to make it permanent) you can just use div with 'discussion_bubble' class on it, and content of div is what will be shown.

== Translations ==

See [[Translations]]

== Players panels ==

=== Update players score ===

The column player_score from the player table is automatically loaded into this.scoreCtrl and therefore into the stars location on the player board. This occurs sometime after the game setup() function. However this score must be updated as the game progresses using notifications.

Note: this.scoreCtrl[player_id] is object of class [[Counter]], you can use other counter API.

Increase a player score (with a positive or negative number):

<pre>
this.scoreCtrl[ player_id ].incValue( score_delta );
</pre>

Set a player score to a specific value:

<pre>
this.scoreCtrl[ player_id ].setValue( new_score );
</pre>

Set a player score to a specific value with animation:

<pre>
this.scoreCtrl[ player_id ].toValue( new_score );
</pre>

Typical usage would be (that will process 'score' notification):
<pre>
setupNotifications : function() {
...
dojo.subscribe('score', this, "notif_score");
},
notif_score: function(notif) {
this.scoreCtrl[notif.args.player_id].setValue(notif.args.player_score);
},
</pre>

=== Adding stuff to player's panel ===

At first, create a new "JS template" string in your template (tpl) file:

(from Gomoku example)
<pre>
var jstpl_player_board = '\<div class="cp_board">\
<div id="stoneicon_p${id}" class="gmk_stoneicon gmk_stoneicon_${color}"></div><span id="stonecount_p${id}">0</span>\
</div>';
</pre>

Then, you add this piece of code in your JS file to add this template to each player panel:

<pre>
// Setting up player boards
for( var player_id in gamedatas.players )
{
var player = gamedatas.players[player_id];

// Setting up players boards if needed
var player_board_div = $('player_board_'+player_id);
dojo.place( this.format_block('jstpl_player_board', player ), player_board_div );
}
</pre>

(Note: the code above is of course from your "setup" function in your Javascript).

Very often, you have to distinguish current player and others players. In this case, you just have to create another JS template (ex: jstpl_otherplayer_board) and use it when "player_id" is different than "this.player_id".

=== Fixing Player Panel heights ===

You may find that the player panels don't automatically resize when adding something to (or removing something from) a player panel while the display is in portrait mode (i.e. the player summary panels are at the top of the screen rather than down the right side).

When this happens, call <pre>this.adaptPlayersPanels();</pre> This recalculates the layout and also adjusts the position of the actionbar for you.

=== Player's panel disabling/enabling ===

'''this.disablePlayerPanel(player_id: number): void'''

Disable given player panel (the panel background become gray).

Usually, this is used to signal that this played passes, or will be inactive during a while.

Note that the only effect of this is visual. There are no consequences on the behaviour of the panel itself.

'''this.enablePlayerPanel(player_id:number): void'''

Enable a player panel that has been disabled before.

'''this.enableAllPlayerPanels(): void'''

Enable all player panels that has been disabled before.

=== Player order ===

'''this.updatePlayerOrdering(): void'''

This function makes sure that player order in player's panel matches this.gamedatas.playerorder and its normally called by framework.
You can call it yoursel if you change this.gamedatas.playerorder from notification.
Also you can override this function to change defaults OR insert a non-player panel [[BGA_Studio_Cookbook#Inserting_non-player_panel]].

=== Counters ===
Note: there is bga component called "ebg/counter" this API is not using it, these methods
below declared right in core game. If you need animation for counters use ebg/counter

To use this API just create a counter dom element like this (class does not really matter)
<pre>
<div class="counter" id="bread"></div>
<div class="counter" id="coin"></div>
</pre>
The "bread" will the counter name.

The php code should send all "counters" data from getAllDatas() method like this

game.php
<pre>
protected function getAllDatas() {
// (the key must match counter_name)
$result['counters']=[
'bread' => [
'counter_name' => 'bread',
'counter_value' => 3
],
'coin' => [
'counter_name' => 'coin',
'counter_value' => 5
]
];
return $result;
}
</pre>

'''setCounter(counter_name: stirng, new_value: string | number): void'''

updates the global this.gamedatas.counters and value of node $(counter_name)
<pre>
notif_counter: function(notif) {
this.setCounter(notif.args.counter_name, notif.args.counter_value);
},
</pre>

'''incCounter(counter_name: string, delta: number): void'''
<pre>
notif_counter : function(notif) {
this.incCounter(notif.args.counter_name, notif.args.inc);
},
</pre>

'''updateCounters(counters: object): void'''

Useful for updating game counters in the player panel (such as resources).
'counters' arg is map of counters (the key must match counter_name)
{
'bread': {
'counter_name' : 'bread',
'counter_value' => 3
},
'coin': {
'counter_name' : 'coin',
'counter_value' => 5
}
}
All counters MUST be referenced in this.gamedatas.counters (means they should be send from php) and will be updated.
DOM objects referenced by 'counter_name' will have their innerHTML updated with 'counter_value'.

Usually you call this from notification

<pre>
notif_counter : function(notif) {
this.updateCounters(notif.args.counters);
},
</pre>

== BGA GUI components ==

BGA framework provides some useful ready-to-use components for the game interface:

[[Studio#BGA_Studio_game_components_reference]]

Note that each time you are using an additional component, you must declare it at the top of your Javascript file in the list of modules used.

Example if you are using "ebg.stock":
<pre>
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/stock" /// <=== we are using ebg.stock module
],
</pre>

== BGA Buttons ==

=== Basic Button ===

'''this.addActionButton(id: string, label: string, method: string | eventhandler, destination?: string, blinking?: boolean, color?: string): void'''

You can use this method to add an action button in the main action status bar (or other places).

Arguments:
* id: an element ID that should be unique in your HTML DOM document.
* label: the text of the button. Should be translatable (use _() function). Note: this can also be any html, such as "<div class='brick'></div>", see example below on how to make image action buttons.
* method: the name of your method that must be triggered when the player clicks on this button (can be name of the method on game class or handler).
* destination (optional): id of parent on where to add button, ONLY use in rare cases if location is not action bar. Use '''null''' as value if you need to specify other arguments.
* blinking (optional): if set to '''true''', the button is going blink to catch player's attention. Please DO NOT abuse blinking button. If you need button to blink after some time passed add class 'blinking' to the button later.
* color: could be '''blue''' (default), '''red''','''gray''' or '''none'''.

You should only use this method in your "onUpdateActionButtons" method. Usually, you use it like this:

<pre>
onUpdateActionButtons: function( stateName, args ) {
if (this.isCurrentPlayerActive()) {
switch( stateName ) {
case 'giveCards':
this.addActionButton( 'giveCards_button', _('Give selected cards'), 'onGiveCards' );
this.addActionButton( 'pass_button', _('Pass'), () => this.bgaPerformAction('actPass') );
break;
}
}
},
</pre>

In the example above, we are adding a "Give selected cards" button in the case we are on game state "giveCards". When player clicks on this button, it triggers our "onGiveCards" method.

Example using blinking red button:
<pre>
this.addActionButton( 'button_confirm', _('Confirm?'), 'onConfirm', null, true, 'red');
</pre>

If you want to call the handler with arguments, you can use arrow functions, like this:
<pre>
this.addActionButton( 'commit_button', _('Confirm'), () => this.onConfirm(this.selectedCardId), null, false, 'red');
</pre>

=== Image Button ===

You can use the same method, but add extra class to a button to disable the padding and style it, i.e.
<pre>
this.addActionButton( 'button_brick', '<div class="brick"></div>', ()=>{... on brick ...}, null, null, 'gray');
dojo.addClass('button_brick','bgaimagebutton');
</pre>

where

<pre>
.bgaimagebutton {
padding: 0px 12px;
min-height: 28px;
border: none;
}
</pre>

If you use this a lot, you can define a helper function, i.e.
<pre>
/**
* This method can be used instead of addActionButton, to add a button which is an image (i.e. resource). Can be useful when player
* need to make a choice of resources or tokens.
*/
addImageActionButton: function(id, div, handler, bcolor, tooltip) {
if (typeof bcolor == "undefined") {
bcolor = "gray";
}
// this will actually make a transparent button id color = gray
this.addActionButton(id, div, handler, null, false, bcolor);
// remove border, for images it better without
dojo.style(id, "border", "none");
// but add shadow style (box-shadow, see css)
dojo.addClass(id, "shadow bgaimagebutton");
// you can also add additional styles, such as background
if (tooltip) {
dojo.attr(id, "title", tooltip);
}
return $(id);
},
</pre>

=== Disabling Button ===

You can disable the '''bgabutton''' by adding the css class '''disabled''' in you js. The disabled button is still visible but is grey and not clickable.
For example in the '''onUpdateActionButtons''' :
<pre>
this.addActionButton('play_button_id', _('Play 1 to 3 cards'), 'playFunctionButton');
if (condition) {
dojo.addClass('play_button_id', 'disabled');
}
</pre>

=== Custom Buttons ===

You can create a custom button, but the BGA framework provides a standard button that requires only .css classes: '''bgabutton''' and '''bgabutton_${color}'''.

'''Examples:'''

<pre>
<a href="#" id="my_button_id" class="bgabutton bgabutton_blue"><span>My blue button</span></a>

<a href="#" id="my_button_id" class="bgabutton bgabutton_red bgabutton_big"><span>My big red button</span></a>
</pre>

'''Note''': To see it in action, check out ''Coloretto''.

=== Button outside of action bar ===

Use addActionButton() method with destination argument set
<pre>
this.addActionButton( 'commit_button', _('Confirm'), 'onConfirm', 'player_board', true, 'red');
</pre>

in example above the button will be place on object with id 'player_board'

== Image loading ==

See also [[Game_art:_img_directory]].

'''Be careful''': by default, ALL images of your img directory are loaded on a player's browser when he loads the game. For this reason, don't let in your img directory images that are not useful, otherwise it's going to slowdown the game load.

'''this.dontPreloadImage(image_file_name: string)'''

Using dontPreloadImage, you tell the interface to not preload a specific image in your img directory.

Example of use:
<pre>
this.dontPreloadImage( 'cards.png' );
</pre>

This is particularly useful if for example you have 2 different themes for a game. To accelerate the loading of the game, you can specify to not preload images corresponding to the other theme.

Another example of use: in "Gosu" game with Kamakor extension, you play with 5 sets of cards among 10 available. Cards images are organized by sets, and we only preload the images corresponding to the 5 current sets with '''ensureSpecificGameImageLoading( image_file_names_array )'''.
<pre>
// By default, do not preload anything
this.dontPreloadImage( 'cards.png' );
this.dontPreloadImage( 'clan1.png' );
this.dontPreloadImage( 'clan2.png' );
this.dontPreloadImage( 'clan3.png' );
this.dontPreloadImage( 'clan4.png' );
this.dontPreloadImage( 'clan5.png' );
this.dontPreloadImage( 'clan6.png' );
this.dontPreloadImage( 'clan7.png' );
this.dontPreloadImage( 'clan8.png' );
this.dontPreloadImage( 'clan9.png' );
this.dontPreloadImage( 'clan10.png' );
var to_preload = [];
for( i in this.gamedatas.clans )
{
var clan_id = this.gamedatas.clans[i];
to_preload.push( 'clan'+clan_id+'.png' );
}

this.ensureSpecificGameImageLoading( to_preload );

</pre>

'''Note:''' You don't need to specify to not preload game box images (game_box.png, game_box75.png...) since they are not preloaded by default.

'''this.ensureSpecificGameImageLoading(list: string[])'''

This is oppostive of dontPreloadImage - its ensure specific images is loaded. Note: only makes sense if preload list is empty, otherwise everything is loaded anyway

'''load specific images'''
All images that will be preloaded stored in g_img_preload. If you want to override it directly - there is no API, but you can do this in GAME constructor

g_img_preload = ['tokens.png', 'trains.png', 'loc_plan.png', 'eng.png', 'eng-back.png'];

You can also set it to empty array and call ensureSpecificGameImageLoading() on specific images

== Sounds ==

Add a custom sound and make it load with your interface:

Add this in your template (.tpl) file:
<pre>
<audio id="audiosrc_<gamename>_<yoursoundname>" src="{GAMETHEMEURL}img/<gamename>_<yoursoundname>.mp3" preload="none" autobuffer></audio>
<audio id="audiosrc_o_<gamename>_<yoursoundname>" src="{GAMETHEMEURL}img/<gamename>_<yoursoundname>.ogg" preload="none" autobuffer></audio>
</pre>

Note: this is a requirement to provide both a mp3 and a ogg file with the names <code><gamename>_<yoursoundname>[.ogg][.mp3]</code>.

Play the sound (from your .js file):

<pre>
playSound('<gamename>_<yoursoundname>'); // do not add 'this.' - its a global function
</pre>

Disable the standard "move" sound for this move (to replace it with your custom sound):

Add this to your notification handler:

<pre>
this.disableNextMoveSound();
</pre>

Note: it only disable the sound for the next move.

== Title bar and states ==

=== Client states ===

Client states is a way to simulate the state transition but without actually going
to server. It is usefull when you need to ask user multiple questions before you
send things to server

'''this.setClientState(newState: string, args: object)'''

Example:
this.setClientState("client_playerPicksLocation", {
descriptionmyturn : _("${you} must select location"),
});

For more information see [[BGA_Studio_Cookbook#Multi_Step_Interactions:_Select_Worker.2FPlace_Worker_-_Using_Client_States]]

'''this.restoreServerGameState()'''
If you are in client state it will restore the current server state (cheap undo)

'''this.on_client_state'''
Boolean indicating that we are in client state

=== Title bar ===
If you simply want to show something in title bar you can do it directly
$('pagemaintitletext').innerHTML = text;

This however will not work with parameters and will not draw You in color,
if you want to do proper args rendering use method below

;'''this.removeActionButtons()'''
Removes all buttons from title bar

;'''this.updatePageTitle()'''
:This function allows to update the current page title and turn description according to the game state arguments. If the current game state description this.gamedatas.gamestate.descriptionmyturn is modified before calling this function it allows to update the turn description without changing state. This will handle arguments substitutions properly.

Note: this functional also will calls this.onUpdateActionButtons, if you want different buttons then state defaults, use method in example to replace them, if it becomes too clumsy use client states (see above)

Example from Terra Mystica:
<pre>
onClickFavorTile: function( evt ) {
...
if ( ... ) {
this.gamedatas.gamestate.descriptionmyturn = _('Special action: ') + _('Advance 1 space on a Cult track');
this.updatePageTitle();
this.removeActionButtons();
this.addActionButton( ... );
...
return;
}
...

}
</pre>

== User preferences ==
'''this.getGameUserPreference(pref_id)'''

Return the value of a user preference. It will return the value currently selected in the select combo box, in the top-right menu.

'''this.setGameUserPreference(pref_id, value)'''

Programmatically change a user preference. It will have the same effect as if the player changed the value in the select combo box, in the top-right menu.

'''this.onGameUserPreferenceChanged'''

A callback you can define if you want to be notified when a user changes a user preference.

Example:<pre>
onGameUserPreferenceChanged: function(pref_id, pref_value) {
switch (pref_id) {
case 201:
document.getElementsByTagName('html')[0].classList.toggle('dark-background', pref_value == 2);
break;
}
}
</pre>

== Other useful stuff ==

'''dojo.hitch'''

With dojo.hitch, you can create a callback function that will run with your game object context whatever happen.

Typical example: display a BGA confirmation dialog with a callback function created with dojo.hitch:

<pre>
this.confirmationDialog( _('Are you sure you want to make this?'), dojo.hitch( this, function() {
this.bgaPerformAction('makeThis');
} ) );
</pre>

In the example above, using dojo.hitch, we ensure that the "this" object will be set when the callback is called.

NOTE: In modern JS there are lambdas that eliminate need for that, the example above will look like this
<pre>
this.confirmationDialog( _('Are you sure you want to make this?'), () => this.bgaPerformAction( 'makeThis') );
</pre>

;'''onScreenWidthChange()'''
:This function can be overridden in your game to manage some resizing on the client side when the browser window is resized. This function is also triggered at load time, so it can be used to adapt to the :viewport size at the start of the game too.

; this.bRealtime
: Return true if the game is in realtime. Note that having a distinct behavior in realtime and turn-based should be exceptional.

; g_replayFrom
: Global contains replay number in live game, it is set to undefined (i.e. not set) when it is not a replay mode, so consequentially the good check is '''typeof g_replayFrom != 'undefined'''' which returns true if the game is in replay mode <i>during the game</i> (the game is ongoing but the user clicked "replay from this move" in the log)

; g_archive_mode
: Returns true if the game is in archive mode <i>after the game</i> (the game has ended)

; this.instantaneousMode
: Returns true during replay/archive mode if animations should be skipped. Only needed if you are doing custom animations. (The BGA-provided animation functions like <i>this.slideToObject()</i> automatically handle instantaneous mode.)
: Technically, when you click "replay from move #20", the system replays the game from the very beginning with moves 0 - 19 happening in instantaneous mode and moves 20+ happening in normal mode.

; g_tutorialwritten
: Returns an object like the below if the game is in tutorial mode, or undefined otherwise. Tutorial mode is a special case of archive mode where comments have been added to a previous game to teach new players the rules.
{
author: "91577332",
id: "576",
mode: "view"
status: "alpha"
version_override: null
viewer_id: "84554161"
}

'''getBgaEnvironment(): string'''
: Returns "studio" for studio and "prod" for production environment (i.e. where games current runs). Only useful for debbugging hooks.
Note: alpha server is also "prod"

[[Category:Studio]]

Game interface logic: Game.js

2024-09-25T16:34:36Z

Sguzzer Gunayer: /* Accessing Players Information */

{{Studio_Framework_Navigation}}

__TOC__

This is the main file for your game interface. Here you will define:

* Which actions on the page will generate calls to the server.
* What happens when you get a notification for a change from the server and how it will show in the browser.
* Setup user interface

== File structure ==

The details of how the file is structured are described below with comments in the code skeleton provided to you.

Here is the basic structure:

* '''constructor''': here you can define global variables for your whole interface.
* '''setup''': this method is called when the page is refreshed, and sets up the game interface.
* '''onEnteringState''': this method is called when entering a new game state. You can use it to customize the view for each game state.
* '''onLeavingState''': this method is called when leaving a game state.
* '''onUpdateActionButtons''': called on state changes, in order to add action buttons to the status bar. Note: in a multipleactiveplayer state, it will be called when another player has become inactive.
* ''(utility methods)'': this is where you can define your utility methods.
* ''(player's actions)'': this is where you can write your handlers for player actions on the interface (example: click on an item).
* '''setupNotifications''': this method associates notifications with notification handlers. For each game notification, you can trigger a javascript method to handle it and update the game interface.
* ''(notification handlers)'': this is where you define the notifications handlers associated with notifications in '''setupNotifications''', above.

More details:

'''setup(gamedatas: object) '''
This method must set up the game user interface according to current game situation specified in parameters.
The method is called each time the game interface is displayed to a player, ie:

* when the game starts
* when a player opens a game in the browser later
* when a player refreshes the game page (F5)
* when player does a server side Undo

"gamedatas" argument contains all data retrieved by your "getAllDatas" PHP method and some more.

'''onEnteringState(stateName: string, args: { args: any } | null): void'''

This method is called each time we enter a new game state.
You can use this method to perform some user interface changes at this moment.
To access state arguments passed via calling php arg* method use args?.args.
Typically you would do something only for active player, using this.isCurrentPlayerActive() check.
It is also called (for the current game state only) when doing a browser refresh (after the setup method is called).

'''Warning''': for multipleactiveplayer states:
the active players are NOT active yet so you must use onUpdateActionButtons to perform the client side operation which depends on a player active/inactive status.
If you are doing initialization of some structures which do not depend on the active player, you can just replace (this.isCurrentPlayerActive()) with (!this.isSpectator)
for the main switch in that method.

See more details in [[Your_game_state_machine:_states.inc.php#Difference_between_Single_active_and_Multi_active_states]]

'''onLeavingState(stateName: string): void'''

This method is called each time we leave a game state.
You can use this method to perform some user interface changes at this point (i.e. cleanup).

'''onUpdateActionButtons(stateName: string, args: object | null): void'''

In this method you can manage "action buttons" that are displayed in the action status bar and highlight active UI elements.
To access state arguments passed via calling php arg* method use '''args''' parameter. Note: args can be null! For '''game''' states and when you don't supply state args function - it is null.
This method is called when the active or multiactive player changes. In a classic "activePlayer" state this method is called before the onEnteringState state.
In multipleactiveplayer state it is a mess. The sequencing of calls depends on whether you get into that state from transitions OR from reloading the whole game (i.e. F5).

See more details in [[Your_game_state_machine:_states.inc.php#Difference_between_Single_active_and_Multi_active_states]]

== Dojo framework ==

BGA uses the [http://dojotoolkit.org/ Dojo Javascript framework].

The Dojo framework allows us to do complex things more easily. The BGA framework uses Dojo extensively.

To implement a game, you only need to use a few parts of the Dojo framework. All the Dojo methods you need are described on this page.

== Javascript minimization (after July 2020) ==

For performance reasons, when deploying a game the javascript code is minimized using '''terser''' (https://github.com/terser/terser). This minifier works with modern javascript syntax. From your project "Manage game" page, you can now test a minified version of your javascript on the studio (and revert to the original).

NB: it has been reported that there is an issue with this minifier and percentage values for opacity.

== Accessing Players Information ==

'''this.player_id: number'''
id of the player who is looking at the game. The player may not be part of the game (i.e. spectator)
if (notif.args.player_id == this.player_id) {
...
}

'''this.isSpectator: boolean'''
Flag set to true if the user at the table is a spectator (not a player).

Example:
<pre>
if (this.isSpectator) {
this.player_color = 'ffffff';
} else {
this.player_color = gamedatas.players[this.player_id].color;
}
</pre>

Note: If you want to hide an element from spectators, you should use [[Game_interface_stylesheet:_yourgamename.css#spectatorMode|CSS 'spectatorMode' class]].

You may consider making a function like this, to detect if the game is in a read-only state (i.e. non-interactive):
// Returns true for spectators, instant replay (during game), archive mode (after game end)
isReadOnly: function () {
return this.isSpectator || typeof g_replayFrom != 'undefined' || g_archive_mode;
}

'''this.gamedatas: object'''
Contains the initial set of data to init the game, created at game start or by game refresh (F5).
You can update it as needed to keep an up-to-date reference of the game on the client side if you need it, however most of the time this is unnecessary.

Note: In hotseat mode, the framework does not keep this.gamedatas of hotseat players and shares the same set as the main player to store data.

Note: be careful when you update this data structurally, many framework functions expect data to be certain way and they will break if they see something else.

Typical example of accessing player's info
<pre>
for (var player_id in this.gamedatas.players) {
var playerInfo = this.gamedatas.players [player_id];
var c = playerInfo.color;
var name = playerInfo.name;
// do something
}
</pre>

'''this.isCurrentPlayerActive(): boolean'''
Returns true if the player on whose browser the code is running is currently active (it's his turn to play). Note: see remarks above about usage of this function inside onEnteringState method.
if (this.isCurrentPlayerActive()) ...

'''this.getActivePlayerId(): number'''
Return the ID of the active player, or null if we are not in an "activeplayer" type state.
if (this.player_id == this.getActivePlayerId()) ...

'''this.getActivePlayers(): number[]'''
Return an array with the IDs of players who are currently active (or an empty array if there are none).

== Accessing and manipulating the DOM ==

=== Element by Id ===

'''$(elementId: ElementOrId)'''

The $ function is used to get an HTML element using its "id" attribute.

Example: modify the content of a "span" element:

<pre>
In your HTML code:
<span id="a_value_in_the_game_interface">1234</span>

In your Javascript code:
$('a_value_in_the_game_interface').innerHTML = "9999";
</pre>

Note: It is safe to use if you don't know if variable is string (id of element) or element itself, i.e.
<pre>
foo: function(card) {
card = $(card); // now its node, no need to write if (typeof card === 'string') ...
// but its good idea to check for null here
...
}
</pre>

'''getElementById(elementId: string)'''

Note: $() is the standard method to access some HTML element with the BGA Framework. You can use '''getElementById''' but a longer to type and less handy as it does not do some checks.

=== Style ===

'''dojo.style(node: ElementOrId, styleName: string, styleValue: any): void'''

With dojo.style you can modify the CSS property of any HTML element in your interface.

Examples:

<pre>
// Make an element disappear
dojo.style( 'my_element', 'display', 'none' );

// Give an element a 2px border
dojo.style( 'my_element', 'borderWidth', '2px' );

// Change the background position of an element
// (very practical when you are using CSS sprites to transform an element to another)
dojo.style( 'my_element', 'backgroundPosition', '-20px -50px' );
</pre>

Note: if you have to modify several CSS properties of an element, or if you have a complex CSS transformation to do, you should consider using dojo.addClass/dojo.removeClass (see below).

You can also use object to set multiple values
<pre>
dojo.setStyle("thinger", {
"opacity": 0.5,
"border": "3px solid black",
"height": "300px"
});
</pre>

'''this.addStyleToClass(cssClassName: string, styleName: string, styleValue: any):''' '''void'''

Same as dojo.style(), but for all the nodes set with the specified cssClassName
Equivalent of

dojo.query(`.${aclass}`).style(styleName, styleValue)

<pre>
dojo.query("#baz > div").style({
opacity:0.75,
fontSize:"13pt"
});
</pre>

'''Vanilla JS style'''
$('my_element').style.display='none'; // set
var display = $('my_element').style.display; // get
$('my_element').style.removeProperty('display'); // remove

=== Classes ===

'''dojo.addClass(node: ElementOrId, classes: string): void'''

'''dojo.removeClass(node: ElementOrId, classes: string): void'''

'''dojo.hasClass(node: ElementOrId, aclass: string): void'''

'''dojo.toggleClass(node: ElementOrId, aclass: string): void'''

In many situations, many small CSS property updates can be replaced by a CSS class change (i.e., you add a CSS class to your element instead of applying all modifications manually).

Advantages are:
* All your CSS stuff remains in your CSS file.
* You can add/remove a list of CSS modifications with a simple function and without error.
* You can test whether you applied the CSS to an element with the '''dojo.hasClass''' method.

Example from ''Reversi'':

<pre>
// We add "possibleMove" to an element
dojo.addClass( 'square_'+x+'_'+y, 'possibleMove' );

// In our CSS file, the class is defined as:
.possibleMove {
background-color: white;
opacity: 0.2;
filter:alpha(opacity=20); /* For IE8 and earlier */
cursor: pointer;
}

// So we've applied 4 CSS property changes in one line of code.

// ... and when we need to check if a square is a possible move on the client side:
if( dojo.hasClass( 'square_'+x+'_'+y, 'possibleMove' ) )
{ ... }

// ... and if we want to remove all possible moves in one line of code (see "dojo.query" method):
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );
</pre>

'''Vanilla JS classList'''

This is the only exception where dojo versions are better
// add class
$(token_id).classList.addClass('possibleMove');
// remove class
$(token_id).classList.removeClass('possibleMove');
// add 2 classes
const myclasses = ['a','b'];
$(token_id).classList.addClass(...myclasses);
// add classes to query result
document.querySelectorAll(".hand .card").forEach((node)=>node.classList.addClass('possibleMove'));

=== Attributes ===

;dojo.attr

With dojo.attr you can access or change the value of an attribute or property of any HTML element in your interface.

Exemple:
<pre>
// Get the title of a node
var title = dojo.attr( id, 'title' );
// Change the height of a node
dojo.attr( 'img_growing_tree', 'height', 100 );
</pre>

'''Vanilla JS attr'''

$(token).id=new_id; // set attr for "id"
var id = $(token).id; // get

=== Queries ===

'''dojo.query(cssSelector: string): Element[]'''

With dojo.query, you can query a bunch of HTML elements with a single function, with a "CSS selector" style.

Example:
<pre>
// All elements with class "possibleMove":
var elements = dojo.query( '.possibleMove' );

// Count number of tokens (i.e., elements of class "token") on the board (i.e., the element with id "board"):
dojo.query( '#board .token' ).length;
</pre>

But what is really cool with dojo.query is that you can combine it with almost all methods above.

Examples:
<pre>
// Trigger a method when the mouse enter in any element with class "meeple":
dojo.query( '.meeple' ).connect( 'onmouseenter', this, 'myMethodToTrigger' );

// Hide all meeples who are on the board
dojo.query( '#board .meeple' ).style( 'display', 'none' );
</pre>

'''Vanilla JS query'''

var cards=document.querySelectorAll(".hand .card");// all cards in all hands
var cards=$('hand').querySelectorAll(".card");// all cards in specific hand
var card=document.querySelector(".hand .card");// first card or null if none (super handy)

=== Creating and Destroying elements ===

'''dojo.empty(node: ElementOrId)'''

Remove all children of the node element
dojo.empty('my_hand');

'''dojo.destroy(node: ElementOrId)'''

Remove the element
dojo.destroy('my_token');

dojo.query(".green", mynode).forEach(dojo.destroy); // this remove all subnode of class green from mynode

'''dojo.create(tag: string, attributes?: obj, parent?: ElementOrId): Element'''

Create element

dojo.create("div", { class: "yellow_arrow" }, parent); // this creates div with class yellow_array and places it in "parent"

'''this.format_block(name: string, args: object): string'''
This bga function that takes global var from template file and substitute variables, typical use would be

var player = gamedatas.players[player_id];
var div = this.format_block('jstpl_player_board', player ); // var jstpl_player_board = ... is defined in .tpl file
Note: result is trimmed

'''this.format_string(name: string, args: object): string'''
This bga function just substitute variables in a string, i.e.
<pre>
var div = this.format_string('<div color="${player_color}"></div>', {player_color: '#ff0000'} );
</pre>
Note: result is trimmed

Note: this can be replaced by using backquoted string now:
const player_color = '#ff0000';
const div = `<div color="${player_color}"></div>`;

'''this.format_string_recursive'''
This bga function is similar to this.format_string but is capable of processing recursive argument structures and translations. It is used to format server notifications.

TODO: find better place for these function docs

=== Moving elements ===

'''dojo.place(node: string | Element, refNode: ElementOrId, pos?: string | number): Element'''

dojo.place is the best function to insert HTML code somewhere in your game interface without breaking something. It is much better to use than the '''innerHTML=''' method if you must insert HTML tags and not only values.

node:

Can be a String or a DOM node. If it is a string starting with “<”, it is assumed to be an HTML fragment, which will be created. Otherwise it is assumed to be an id of a DOM node.

<pre>
// Insert your HTML code as a child of a container element
dojo.place( "<div class='foo'></div>", "your_container_element_id" );
</pre>

pos:

Optional argument. Can be a number or one of the following strings: “before”, “after”, “replace”, “only”, “first”, or “last”. If omitted, “last” is assumed.

"replace": Replace the container element with my_node element

"first": Places the node as a child of the reference node. The node is placed as the first child.

"last" (default): Places the node as a child of the reference node. The node is placed as the last child.

"before": places the node right before the reference node.

"after": places the node right after the reference node.

"only": replaces all children of the reference node with the node.

positive integer: This parameter can be a positive integer. In this case, the node will be placed as a child of the reference node with this number (counting from 0). If the number is more than number of children, the node will be appended to the reference node making it the last child.

<pre>
// Replace all children of container with my_node
dojo.place( $('my_node'), "your_container_element_id", "only" );
</pre>

See also full doc on dojo.place: [https://dojotoolkit.org/reference-guide/1.7/dojo/place.html]

Usually, when you want to insert some piece of HTML in your game interface, you should use "[[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl#Javascript_templates|Javascript templates]]".

But you can also relocate elements like that. Note: it won't animate if you do that.

'''this.placeOnObject(mobile_obj: ElementOrId, target_obj: ElementOrId): void'''

places mobile_obj on target_obj, set the absolute positions and centers the mobile_obj on target_obj,
effect is immediate

This is not really an animation, but placeOnObject is frequently used before starting an animation.

Example:
<pre>
// (We just created an object "my_new_token")

// Place the new token on current player board
this.placeOnObject( "my_new_token", "overall_player_board_"+this.player_id );

// Then slide it to its position on the board
this.slideToObject( "my_new_token", "a_place_on_board" ).play();
</pre>

'''this.placeOnObjectPos(mobile_obj: ElementOrId, target_obj: ElementOrId, target_x: number, target_y: number): void'''

This method works exactly like placeOnObject, except than you can specify some (x,y) coordinates (in px). This way, the center of "mobile_obj" will be placed to the specified x,y position relatively to the center of "target_obj".

''Note: the placement works differently from this.slideToObjectPos'', since coordinates are calculated based on the center of objects.

'''this.attachToNewParent(mobile_obj: ElementOrId, target_obj: ElementOrId): void'''

With this method, you change the HTML parent of "mobile_obj" element without moving it.
"target_obj" is the new parent of this element. The beauty of
attachToNewParent is that the mobile_obj element DOES NOT MOVE during this process.

What happens is that the method calculate a relative position of mobile_obj to make sure it does not move after the HTML parent changes.

Why using this method?

Changing the HTML parent of an element can be useful for the following reasons:
* When the HTML parent moves, all its child are moving with them. If some game elements is no more linked with a parent HTML object, you may want to attach it to another place.
* The z_order (vertical order of display) depends on the position in the DOM, so you may need to change the parent of some game elements when they are moving in your game area.

'''CAREFUL''': this function destroys original object and places a clone onto a new parent, this will break all references to this HTML element (ex: dojo.connect).
If you need version that does not destroy the object but the same otherwise see [[BGA_Studio_Cookbook#Attach_to_new_parent_without_destroying_the_object]]

== Animations ==

===Dojo Animations===

BGA animations is based on Dojo Animation ([http://dojotoolkit.org/documentation/tutorials/1.8/animation/ see tutorial here]).

However, most of the time, you can just use methods below, which are built on top of Dojo Animation.

Note: one interesting method from Dojo that could be useful from time to time is "Dojo.Animation". It allows you to make any CSS property "slide" from one value to another.

Note 2: the slideTo methods are not compatible with CSS transform (scale, zoom, rotate...). If possible, avoid using CSS transform on nodes that are being slided. Eventually, the only possible solution to make these 2 compatible is to disable all CSS transform properties, use slideToObjectPos/placeOnObjectPos, and then apply them again.

===Sliding===

'''this.slideToObject(mobile_obj: ElementOrId, target_obj: ElementOrId, duration?: number, delay?: number): Animation'''

You can use slideToObject to "slide" an element to a target position.

Sliding element on the game area is the recommended and the most used way to animate your game interface. Using slides allow players to figure out what is happening on the game, as if they were playing with the real boardgame.

The parameters are:
* mobile_obj: the ID of the object to move. This object must be "relative" or "absolute" positioned.
* target_obj: the ID of the target object. This object must be "relative" or "absolute" positioned. Note that it is not mandatory that mobile_obj and target_obj have the same size. If their size are different, the system slides the center of mobile_obj to the center of target_obj.
* duration: (optional) defines the duration in millisecond of the slide. The default is 500 milliseconds.
* delay: (optional). If you defines a delay, the slide will start only after this delay. This is particularly useful when you want to slide several object from the same position to the same position: you can give a 0ms delay to the first object, a 100ms delay to the second one, a 200ms delay to the third one, ... this way they won't be superposed during the slide.

BE CAREFUL: The method returns an dojo.fx animation, so you can combine it with other animation if you want to. It means that you have to call the "play()" method, otherwise the animation WON'T START.

Example:
<pre>
this.slideToObject( "some_token", "some_place_on_board" ).play();
</pre>

'''this.slideToObjectPos(mobile_obj: ElementOrId, target_obj: ElementOrId, target_x: number, target_y: number, duration?: number, delay?: number): Animation'''

This method does exactly the same as "slideToObject", except than you can specify some (x,y) coordinates. This way, "mobile_obj" will slide to the specified x,y position relatively to "target_obj".

Example: slide a token to some place on the board, 10 pixels from the top:
<pre>
this.slideToObjectPos( "some_token", "some_place_on_board", 0, 10 ).play();
</pre>

'''this.slideTemporaryObject(mobile_obj_html: string, parent: ElementOrId, from: ElementOrId, to: ElementOrId, duration?: number, delay?: number): Animation'''

This method is useful when you want to slide a temporary HTML object from one place to another. As this object does not exists before the animation and won't remain after, it could be complex to create this object (with dojo.place), to place it at its origin (with placeOnObject) to slide it (with slideToObject) and to make it disappear at the end.

slideTemporaryObject does all of this for you:
* mobile_obj_html is a piece of HTML code that represent the object to slide.
* parent is the ID of an HTML element of your interface that will be the parent of this temporary HTML object.
* from is the ID of the origin of the slide.
* to is the ID of the target of the slide.
* duration/delay works exactly like in "slideToObject"

Example:
<pre>
this.slideTemporaryObject( '<div class="token_icon"></div>', 'tokens', 'my_origin_div', 'my_target_div' ).play();
</pre>

===Destroy===
'''this.slideToObjectAndDestroy(mobile_obj: ElementOrId, target_obj: ElementOrId, duration?: number, delay?: number): void'''

This method is a handy shortcut to slide an existing HTML object to some place then destroy it upon arrival. It can be used for example to move a victory token or a card from the board to the player panel to show that the player earns it, then destroy it when we don't need to keep it visible on the player panel.

It works the same as this.slideToObject and takes the same arguments, but it starts the animation.

CAREFUL: Make sure nothing is creating the same object at the same time the animation is running, because this will cause some random disappearing effects

Example:
<pre>
this.slideToObjectAndDestroy( "some_token", "some_place_on_board", 1000, 0 );
</pre>

'''this.fadeOutAndDestroy( node: string | Element, duration?: number, delay?: number):''' '''void'''

This function fade out the target node, then destroy it. Its starts the animation.
* duration/delay works exactly like in "slideToObject"

Example:
<pre>
this.fadeOutAndDestroy( "a_card_that_must_disappear" );
</pre>

CAREFUL: the HTML node still exists until during few milliseconds, until the fadeOut has been completed.
Make sure nothing is creating same object at the same time as animation is running, because you will be some random dissapearing effects

===Rotating elements===

This example combines "Dojo.Animation" method and a CSS property transform that allow you to rotate the element.
<pre>
// node is Element we rotating
var animation = new dojo.Animation({
curve: [fromDegree, toDegree],
onAnimate: (v) => {
node.style.transform = 'rotate(' + v + 'deg)';
}
});

animation.play();
</pre>

BGA has its own interface to rotate

'''this.rotateTo(node: string | Element, degree: number): void'''

It starts the animation, and stored the rotation degree in the class, so next time you rotate object - it is additive.
There is no animation hooks in this one, if you need to change any parameters use dojo animation above.

There is also '''rotateInstantTo''' with same signature which does not animate

===Animation Callbacks===

If you wish to run some code only after an animation has completed you can do this by linking a callback method to 'onEnd'.

<pre>
var animation_id = this.slideToObject( mobile_obj, target_obj, 500 );
dojo.connect(animation_id, 'onEnd', () => {
// do something here
});
animation_id.play();
</pre>

If you wish to call a second animation after the first (rather than general code) then you can use a dojo animation chain (see tutorial referenced above).

== Players input ==

=== Connecting ===
'''dojo.connect(element: Element, event: string, context: object, method: eventHandler): any'''

'''dojo.connect(element: Element, event: string, hander: eventHandler): any'''

Used to associate a player event with one of your notification methods.

Example: associate a click on an element ("my_element") with one of our methods ("onClickOnMyElement"):
<pre>
dojo.connect( $('my_element'), 'onclick', this, 'onClickOnMyElement' );
</pre>

Same idea but base on query (i.e. all element of 'pet' class)
dojo.query(".pet").connect('onclick', this, 'onPet');

Note: if you need to disconnect the handler you have to store handler returned from this method, i.e.

<pre>
var handler = dojo.connect(...);
...
dojo.disconnect(handler);
</pre>

If you don't store the handler - you have to destroy the object to disconnect it

Typical function that implements the input handler will look like this

<pre>
onPet: function(event) {
var id = event.currentTarget.id;
console.log('onPet ' + id);
dojo.stopEvent(event);
if (this.gamedatas.gamestate.name == 'playerTurnPet') {
this.bgaPerformAction('actPlayPet', {card: id});
} else {
this.showMoveUnauthorized();
}
}
</pre>

'''this.connect(element: ElementOrId, event: string, method: eventHandler): void'''

Used to associate a player event with one of your notification methods.

this.connect( $('my_element'), 'onclick', 'onClickOnMyElement' );

Or you can use an in-place handler

this.connect( $('my_element'), 'onclick', (e) => { console.log('boo'); } );

Note that this function stores the connection handler. That is the only real difference between '''this.connect''' and '''dojo.connect'''. If you plan to destroy the element you connected, you '''must''' call this.disconnect() to prevent memory leaks.
This function is mainly for permanent objects - if you just want to connect the temp object you should probably not use this method but use dojo.connect which won't require any clean-up.

'''this.connectClass(cssClassName: string, event: string, method: eventHandler): void'''

Same as connect(), but for all the nodes set with the specified cssClassName.

this.connectClass('pet', 'onclick', 'onPet');

'''this.disconnect(element: ElementOrId, event: string): void'''

Disconnect event handler (previously registered with this.connect or this.connectClass).

this.disconnect( $('my_element'), 'onclick');

Note: dynamic connect/disconnect is for advanced cases ONLY, you should always connect elements statically if possible, i.e. in setup() method.

'''this.disconnectAll(): void'''

Disconnect all previously registed event handlers (registered via this.connect or this.connectClass)

this.disconnectAll();

=== Actions ===

'''this.bgaPerformAction(action: string, args?: object, options: object = { lock: true, checkAction: true }): Promise<void>'''

Triggers an action on the backend. This is a combination of checkAction and ajaxcall, returning a Promise which resoves when ajaxcall ends.

This method must be used to send a player input to the game server. '''It should not be triggered programmatically''', especially not in loops, in callbacks, in notifications, or in onEnteringState/onUpdateActionButtons/onLeavingState, in order not to create race conditions or break replay game and tutorial features. It should be used only in reaction to a user action in the interface.

* action: name of the action, as it is written in "possibleactions" of the current state.
* args: an object containing the call parameters to send to the action
* options: options to tweak the call with some defaults. Default is <code>{ lock: true, checkAction: true }</code>.

Example of a standard call without args:
this.bgaPerformAction('pass');

Example of a standard call with action args:
this.bgaPerformAction('actPlayCard', { id: this.selectedCardId });

Example of a call without checking action (because player is inactive in a multiactive state):

this.bgaPerformAction('actChangeMind', {}, { checkAction: false });

Example of a call without lock (because of a special action not directly related to the game flow):

this.bgaPerformAction('actSetAutoBid', { alwaysBidUntil: 500 }, { lock: false, checkAction: false });

Example of call with reaction to exception:
this.bgaPerformAction('actPlayCard', { id: this.selectedCardId }).catch(()=>{ this.selectedCardId = undefined; });

Example of call with reaction to success:
this.bgaPerformAction('actPlayCard', { id: this.selectedCardId }).then(()=>{ this.unselectAll(); });

'''this.ajaxcall(url, parameters, obj_callback, callback, callback_anycase?, ajax_method?: string)'''

''Note: bgaPerformAction is a simpler way to use ajax calls, ajaxcall stays in the doc for legacy reasons only and should not be used in new projects.''

Same warning as '''this.bgaPerformAction''' about using on user action only.

* url: the url of the action to perform. For a game, it must be: "/<mygame>/<mygame>/myAction.html"
* parameters: an array of parameter to send to the game server.
** Note that "lock: true" must always be specified in this list of parameters in order the interface can be locked during the server call. Cannot use lock: false - to not lock it has to be undefined.
** Note: Restricted parameter names (please don't use them):
*** "action"
*** "module"
*** "class"
* obj_callback: must be set to "this".
* callback (non-optional but rarely used): a function to trigger when the server returns result and everything went fine (not used, as all data handling is done via notifications).
* callback_anycase: (optional) a function to trigger when the server returns ok OR error. If no error this function is called with parameter value false. If an error occurred, the first parameter will be set to true, the second will contain the error message sent by the PHP back-end, and the third will contain an error code.
* ajax_method: (optional and rarely used) if you need to send large amounts of data (over 2048 bytes), you can set this parameter to 'post' (all lower-case) to send a POST request as opposed to the default GET. This works, but was not officially documented, so only use if you really need to.

Usage:
<pre>
this.ajaxcall( '/mygame/mygame/actMyAction.html', { lock: true,
arg1: myarg1,
arg2: myarg2
}, this, (result)=>{} );
</pre>

'''this.checkAction(action: string, nomessage?: boolean): boolean '''

Check if player can do the specified action by taking into account:
* if interface is locked it will return false and show message "An action is already in progress", unless nomessage set to true
* if player is not active it will return false and show message "This is not your turn", unless nomessage set to true
* if action is not in list in possible actions (defined by "possibleaction" in current game state) it will return false and show "This move is not authorized now" error (unconditionally).
* otherwise returns true
Example:
<pre>
function onClickOnGameElement( evt ) {
if( this.checkAction( "actMyAction" ) ) {
// Do the action
}
}
</pre>

'''this.checkPossibleActions(action: string): boolean'''

* this is independent of the player being active, so can be used instead of this.checkAction(). This is particularly useful for multiplayer states when the player is not active in a 'player may like to change their mind' scenario. Unlike this.checkAction, this function does NOT take interface locking into account

* if action is not in list in possible actions (defined by "possibleaction" in current game state) it will return false and show "This move is not authorized now" error (unconditionally).
* otherwise returns true

function onChangeMyMind( evt ) {
if( this.checkPossibleActions( "actMyAction" ) ) {
// Do the action
}
}

'''this.checkLock(nomessage?: boolean): boolean'''

When using "lock: true" in ajax call you can use this function to check if interface is in lock state (it will be locked during server call and notification processing).
This check can be used to block some other interactions which do not result in ajaxcall or if you want to suppress errors. Note: normally you only need to use this.checkAction(...), this is for advanced cases.

It will also show error unless nomessage is set to true

function onChangeMyMind( evt ) {
if( this.checkLock() ) {
// Do the action
}
}

== Notifications ==

When something happens on the server side, your game interface Javascript logic received a notification.
If you have not done so yet check what notification are in [[Main_game_logic:_yourgamename.game.php#Notifications]]

Here's how you can handle these notifications on the client side.

=== Subscribe to notifications ===

'''dojo.subscribe(notif_type: string, callback_obj: Object, handler: string|handler)'''
* notif_type - notification type/name send by php server
* callback_obj - usually this
* handler - if string method of callback_obj with name name is called, when notification is called, with notification object as parameter (see below)

Your Javascript "setupNotifications" method is the place where you can subscribe to notifications from your PHP code.

Here's how you associate one of your Javascript method to a notification "playDisc" (from Reversi example):

<pre>
setupNotifications: function() {
...
dojo.subscribe('playDisc', this, "notif_playDisc");
},
</pre>

Note: the "playDisc" corresponds to the name of the notification you define it in your PHP code, in your "notifyAllPlayers" or "notifyPlayer" method.

Then, you have to define your "notif_playDisc" method:

<pre>
notif_playDisc: function(notif) {
// Remove current possible moves (makes the board more clear)
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );
this.addDiscOnBoard( notif.args.x, notif.args.y, notif.args.player_id );
},
</pre>

In a notification handler like our "notif_playDisc" method, you can access all notifications arguments with "notif.args".

Example:

PHP

<pre>
$this->notifyAllPlayers( "apples", clienttranslate('player takes ${count} apples'), [ "count" => 3 ] );
</pre>

JavaScript

<pre>
setupNotifications: function() {
dojo.subscribe( 'apples', this, 'notif_apples' );
},

notif_apples: function(notif) {
//You can access the "count" like this:
alert("count = " + notif.args.count);
}
</pre>

=== The notification Object received by client ===

When sending a notification on your PHP, the client side will receive an Object with the following attributes:

* type - type of the notification (as passed by php function)
* log - the log string passed from php notification
* args - This is the arguments that you passed on your notification method on php
* bIsTableMsg - is true when you use [[Main_game_logic:_yourgamename.game.php#NotifyAllPlayers|NotifyAllPlayers]] method (false otherwise)
* channelorig - information about table ID (formatted as : "/table/t[TABLE_NUMBER]")
* gamenameorig - name of the game
* move_id - ID of the move associated with the notification
* table_id - ID of the table (comes as string)
* time - UNIX GMT timestamp
* uid - unique identifier of the notification
* h - unknown

'' Note that those information were inferred from observation on console log. If an Admin can confirm/correct (and remove this line), you're welcome :)''

=== Ignoring notifications ===

Sometimes you need to ignore some notification on client side. You don't want them to be shown in game log and you don't want them to be handled.

The most common use case is when a player gets private information. They will receive a specific notification (such as "You received Ace of Heart"), while other players would receive more generic notification ("Player received a card").

In X.game.php
<pre>
$this->notifyAllPlayers("dealCard", clienttranslate('${player_name} received a card'), [
'player_id' => $playerId,
'player_name' => $this->getActivePlayerName()
]);

$this->notifyPlayer($playerId, "dealCardPrivate", clienttranslate('You received ${cardName}'), [
"type" => $card["type"],
"cardName" => $this->getCardName($card["type"])
]);
</pre>

The problem with this approach is that the active player will receive two notifications:
* Player1 received a card
* You received Ace of Hearts

Hence, notification ignoring.

NOTE: You can think that it would be possible to send such notification to all players except active just by using notifyPlayer and it seems to work. The problem however is that table spectators would miss such notification and their user interface (and game log) wouldn't be updated. Since there is no way to send notification just to spectators, ignoring the notification (or "filtering") is the only reasonable solution.

'''setIgnoreNotificationCheck(notif_type: string, predicate: ((notif: Notif)=>boolean))'''
This method will set a check whether any of notifications of specific type should be ignored.

The parameters are:
* notif_type: type of the notification
* predicate (notif => boolean): a function that will receive notif object and will return true if this specific notification should be ignored

Before dispatching any notification of this type, the framework will call predicate to check whether notification should be ignored, if it return true - the notification will be dispatched, i.e. logged or handled.

<pre>
this.notifqueue.setIgnoreNotificationCheck( 'dealCard', (notif) => (notif.args.player_id == this.player_id) );
</pre>

IMPORTANT: Remember that this notification is ignored on the client side, but was still received by the client. Therefore it shouldn't contain any private information as cheaters can get it. In other words this is not a way to hide information.

IMPORTANT: When a game is reloaded with F5 or when opening a turn based game, old notifications are replayed as history notification. They are used just to update the game log and are stripped of all arguments except player_id, i18n and any argument present in message. If you use and other argument in your predicate you should '''preserve''' it as explained [[Main_game_logic:_yourgamename.game.php#Notify_players|here]].

=== Synchronous notifications ===

When several notifications are received by your game interface, these notifications are processed immediately, one after the other, in the same exact order they have been generated in your PHP game logic.

However, sometimes, you need to give some time to the players to figure out what happened on the game before jumping to the next notification. Indeed, in many games, there are a lot of automatic actions, and the computer is going to resolve all these actions very fast if you don't tell it not to do so.

As an example, for Reversi, when someone is playing a disc, we want to wait 500 milliseconds before doing anything else in order the opponent player can figure out what move has been played.

Here's how we do this, right after our subscription:
<pre>
dojo.subscribe( 'playDisc', this, "notif_playDisc" );
this.notifqueue.setSynchronous( 'playDisc', 500 ); // Wait 500 milliseconds after executing the playDisc handler
</pre>

-----

It is also possible to control the delay timing dynamically (e.g., using notification args). As an example, maybe your notification 'cardPlayed' should pause for a different amount of time depending on the number or type of cards played.

For this case, use '''setSynchronous''' without specifying the duration and use '''setSynchronousDuration''' within the notification callback.

* NOTE: If you forget to invoke '''setSynchronousDuration''', the game will remain paused forever!

<pre>
setupNotifications: function () {
dojo.subscribe( 'cardPlayed', this, 'notif_cardPlayed' );
this.notifqueue.setSynchronous( 'cardPlayed' ); // wait time is dynamic
...
},

notif_cardPlayed: function (notif) {
// MUST call setSynchronousDuration

// Example 1: From notification args (PHP)
this.notifqueue.setSynchronousDuration(notif.args.duration);
...

// Or, example 2: Match the duration to a Dojo animation
var anim = dojo.fx.combine([
...
]);
anim.play();
this.notifqueue.setSynchronousDuration(anim.duration);
},
</pre>

You can also manually call this.notifqueue.setSynchronousDuration(0) once client operations are finished, but be careful that even fast replay still has a path to call it.

'''WARNING: combining synchronous and ignored notifications'''
You must be careful when combining dynamic synchronous durations (as described above) with ignored notifications. If you have a conditionally ignored notification like this (see below section):

<pre>this.notifqueue.setIgnoreNotificationCheck( 'myNotif', (notif) => (notif.args.player_id == this.player_id) /* or any other condition */ )</pre>

then you CANNOT do

<pre>this.notifqueue.setSynchronous('myNotif');</pre>

as, when the ignored check passes, the notification handler, in which `this.notifqueue.setSychronousDuration` is called, is never called and so the duration is never set and interface locking results.

The workaround is to set a "dummy" time:

<pre>this.notifqueue.setSynchronous('myNotif', 5000);</pre>

whose value is irrelevant but must be large enough to cover the time before the notification handler is called. The large value never actually comes into play because the notification is either ignored, or the synchronous duration is reset to a sensible value inside the handler.

=== Pre-defined notification types ===

'''tableWindow''' - This defines notification to display [[Game_interface_logic:_yourgamename.js#Scoring_dialogs|Scoring Dialogs]], see below.

'''message''' - This defines notification that shows on players log and have no other effect (technically any unhandled notification will do the same but its recommended to use this keyword for consistency)

// You can call this on php side without doing anything on client side
self::notifyAllPlayers( 'message', clienttranslate('hello'), [] );

'''simplePause''' - This notification will just delay other notifications, maybe useful if you know you need some extra time for animation or something. Requires a time parameter.

<pre>
self::notifyAllPlayers( 'simplePause', '', [ 'time' => 500] ); // time is in milliseconds
</pre>

Note: the following types are RESERVED by framework, do not use:

gameStateChange gameStateChangePrivateArg gameStateMultipleActiveUpdate newActivePlayer playerstatus yourturnack clockalert tableInfosChanged playerEliminated tableDecision archivewaitingdelay end_archivewaitingdelay replaywaitingdelay end_replaywaitingdelay replayinitialwaitingdelay end_replayinitialwaitingdelay aiPlayerWaitingDelay replay_has_ended updateSpectatorList wouldlikethink updateReflexionTime undoRestorePoint resetInterfaceWithAllDatas zombieModeFail zombieModeFailWarning aiError skipTurnOfPlayer zombieBack allPlayersAreZombie gameResultNeutralized playerConcedeGame showTutorial showCursor showCursorClick skipTurnOfPlayerWarning banFromTable resultsAvailable switchToTurnbased newPrivateState infomsg

== Tooltips ==

=== Adding static tooltips ===

'''this.addTooltip(nodeId: string, helpStringTranslated: string, actionStringTranslated: string, delay?: number): void'''

Add a simple text tooltip to the DOM node.

Specify 'helpStringTranslated' to display some information about "what is this game element?".
Specify 'actionStringTranslated' to display some information about "what happens when I click on this element?".

You must specify both of the strings. You can only use one and specify an empty string ('') for the other one.

When you pass text directly function _() must be used for the text to be marked for translation! Except for empty string.

Parameter "delay" is optional. It is primarily used to specify a zero delay for some game element when the tooltip gives really important information for the game - but remember: no essential information must be placed in tooltips as they won't be displayed in some browsers (see [[BGA_Studio_Guidelines|Guidelines]]).

Example:
<pre>
this.addTooltip( 'cardcount', _('Number of cards in hand'), '' );
</pre>

Note: this generates static tooltip and attaches to existing dom element, if you need to generate tooltip more dynamically you have to call that method every time information about object is updated or use completely different tehnique, see dynamic tooltips below.

'''this.addTooltipHtml(nodeId: string, html: string, delay?: number): void'''

Add an HTML tooltip to the DOM node (for more elaborate content such as presenting a bigger version of a card).

'''this.addTooltipToClass(cssClass: string, helpStringTranslated: string, actionStringTranslated: string, delay?: number ): void'''

Add a simple text tooltip to all the DOM nodes set with this cssClass. See more details above for this.addTooltip.
this.addTooltipToClass( 'meeple', _('This is A Meeple'), _('Click to tickle') );

IMPORTANT: all concerned nodes must exist and have IDs to get tooltips.

'''this.addTooltipHtmlToClass(cssClass: string, html: string, delay?: number): void'''

Add an HTML tooltip to to all the DOM nodes set with this cssClass (for more elaborate content such as presenting a bigger version of a card).

IMPORTANT: all concerned nodes must exist and have IDs to get tooltips.

=== Removing static tooltips ===

'''this.removeTooltip(nodeId: string): void'''

Remove a tooltip from the DOM node with given id.

=== Advanced tooltips ===

'''force tooltip to open'''

If you want to force tooltip to open in reaction to some other action, i.e. click you can do this

this.tooltips[id].open(id)

where id is the id of the tooltip node where tooltip was installed.

'''dynamic tooltips'''

See [[BGA_Studio_Cookbook#Dynamic_tooltips]]

'''tooltips on mobile'''

Tooltips is very unreliable on mobile, it is recommended to implement some other method to obtaining same information,
such as simple click handler in dedicated "Help" mode or provide dedicated clickable areas such as corner of card.

== Warning messages ==

Sometimes, there is something important that is happening in the game and you have to make sure all players get the message. Most of the time, the evolution of the game situation or the game log is enough, but sometimes you need something more visible.

Ex: someone fulfills one of the end of the game conditions, so this is the last turn.

'''this.showMessage(msg: string, type: string): void'''

showMessage shows a message in a big rectangular area on the top of the screen of the current player, and it dissapears after few seconds (also it will be in the log in some cases).

* "msg" is the string to display. It should be translated.
* "type" can be set to "info", "error", "only_to_log" or custom string. If set to "info", the message will be an informative message on a white background. If set to "error", the message will be an error message on a red background and it will be added to log. If set to "only_to_log", the message will be added to the game log but will not popup at the top of the screen.
If set to custom string, it will be transparent, to use custom type define "head_xxx" in css, where xxx is the type. For example if you want yellow warning, use "warning" as type and add this to css:
.head_warning {
background-color: #e6c66e;
}

Important: the normal way to inform players about the progression of the game is the game log. The "showMessage" is intrusive and should not be used often.

<pre>
notif_messageinfo: function(notif) {
if (!g_archive_mode) {
var message = this.format_string_recursive(notif.log, notif.args);
this.showMessage(_('Announcement:') + " " + message, 'info');
}
},
</pre>

Show message could be used on the client side to prevent user wrong moves before it is send to server.
Example from 'battleship':
<pre>
onGrid: function(event) {
if (checkIfPlayerTriesToFireOnThemselves(event)) {
this.showMessage(_('This is your own board silly!'), 'error');
return;
}
...
},
</pre>

'''this.showMoveUnauthorized(): void'''

Shows predefined user error that move is unauthorized now

<pre>
onPet: function(event) {
if (checkPet(event)==false) {
this.showMoveUnauthorized();
return;
}
...
},
</pre>

== Dialogs ==

=== Confirmation dialog ===

When an important action with a lot of consequences is triggered by the player, you may want to propose a confirmation dialog.

CAREFUL: the general guideline of BGA is to AVOID the use of confirmation dialogs. Confirmation dialogs slow down the game and bother players. The players know that they have to pay attention to each move when they are playing online.

The situations where you should use a confirmation dialog are the following:
* It must not happen very often during a game.
* It must be linked to an action that can really "kill a game" if the player does not pay attention.
* It must be something that can be done by mistake (ex: a link on the action status bar).

'''this.confirmationDialog(message: string, yesHandler: (param: any) => void, noHandler?: (param: any) => void, param?: any): void'''

* message - message will be shown to user, use _() to translate
* yesHandler - non-optional handler to be called on yes
* noHandler - optional handler to called on no
* param - if specified, it will be passed to both handlers
NOTE: this is async function, it does not return anything and you should not do anything after, you must do everything in handlers

How to display a confirmation dialog:
<pre>
this.confirmationDialog(_("Are you sure you want to bake a pie?"), () => {
this.bakeThePie();
});
return; // nothing should be called or done after calling this, all action must be done in the handler
</pre>
With param and both handlers
<pre>
this.confirmationDialog(_("Are you sure you want to bake a pie?"),
(ingredient) => this.bakeThePie(ingredient),
(ingredient) => console.log(`cancelled baking of ${ingredient}`),
'apple');
</pre>

=== Multiple choice dialog ===

You can use this dialog to give user a choice with small amount of options

'''this.multipleChoiceDialog(message: string, choices: string[], callback: (choice: number) => void): void'''
* message - message will be shown to user, use _() to translate
* choices - array of choices
* callback - non-optional handler to be called on choice made, the choice parameter is the INDEX of the choice from the array of choices

NOTE: this is async function, it does not return anything and you should not do anything after, you must do everything in handlers
NOTE: there is no cancel handler, so make sure you gave user a choice to get out of it

Example:
<pre>
const keys = ["0", "1", "5", "10"];
this.multipleChoiceDialog(_("How many bugs to fix?"), keys, (choice) => {
if (choice==0) return; // cancel operation, do not call server action
var bugchoice = keys[choice]; // choice will be 0,1,2,3 here
this.bgaPerformAction("fixBugs", { number: bugchoice });
});
return; // must return here
</pre>

=== Generic Dialogs ===

As a general rule, you shouldn't use dialogs windows.

BGA guidelines specify that all game elements should be displayed on the main screen. Players can eventually scroll down to see game elements they don't need to see anytime, and you may eventually create anchors to move between game area section. Of course dialogs windows are very practical, but the thing is: all players know how to scroll down, and not all players know how to show up your dialog window. In addition, when the dialog shows up, players can't access the other game components.

Sometimes although, you need to display a dialog window. Here is how you do this:

// Create the new dialog over the play zone. You should store the handler in a member variable to access it later
this.myDlg = new ebg.popindialog();
this.myDlg.create( 'myDialogUniqueId' );
this.myDlg.setTitle( _("my dialog title to translate") );
this.myDlg.setMaxWidth( 500 ); // Optional

// Create the HTML of my dialog.
// The best practice here is to use [[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl#Javascript_templates|Javascript templates]]
var html = this.format_block( 'jstpl_myDialogTemplate', {
arg1: myArg1,
arg2: myArg2,
...
} );

// Show the dialog
this.myDlg.setContent( html ); // Must be set before calling show() so that the size of the content is defined before positioning the dialog
this.myDlg.show();

// Now that the dialog has been displayed, you can connect your method to some dialog elements
// Example, if you have an "OK" button in the HTML of your dialog:
dojo.connect($('my_ok_button'), 'onclick', this, (event) => {
event.preventDefault();
this.myDlg.destroy();
});

If necessary, you can remove the default top right corner 'close' icon, or replace the function called when it is clicked:
// Removes the default close icon
this.myDlg.hideCloseIcon();

// Replace the function call when it's clicked
this.myDlg.replaceCloseCallback((event) => { ... });

=== Scoring dialogs ===

Sometimes at the end of a round you want to display a big table that details the points wins in each section of the game.

Example: in Hearts game, we display at the end of each round the number of "heart" cards collected by each player, the player who collected the Queen of Spades, and the total number of points loose by each player.

Scoring dialogs are managed entirely on '''PHP side''', but they are described here as their effects are visible only on client side.

Displaying a scoring dialog is quite simple and is using a special notification type: "tableWindow":
<pre>
// on PHP side:
$this->notifyAllPlayers( "tableWindow", '', array(
"id" => 'finalScoring',
"title" => clienttranslate("Title of the scoring dialog"),
"table" => $table
));
</pre>

The "table" argument is a 2 dimensional PHP array that describes the table you want to display, line by line and column by column.

Example: display an 3x3 array of strings
<pre>
$table = [
[ "one", "two", "three" ], // This is my first line
[ "four", "five", "six" ], // This is my second line
[ "seven", "height", "nine" ] // This is my third line
];
</pre>

As you can see above, in each "cell" of your array you can display a simple string value. But you can also display a complex value with a template and associated arguments like this:
<pre>
$table = [
[ "one", "two", [ "str" => clienttranslate("a string with an ${argument}"), "args" => [ 'argument' => 'argument_value' ] ] ],
[ "four", "five", "six" ],
[ "seven", "height", "nine" ]
];
</pre>

This is especially useful when you want to display player names with colors. Example from "Hearts":
<pre>
$firstRow = [ '' ];
foreach( $players as $player_id => $player ) {
$cell = [ 'str' => '${player_name}',
'args' => [ 'player_name' => $player['player_name'] ],
'type' => 'header'
];
$firstRow[] = $cell;
}
$table[] = $firstRow;
...
</pre>

You can also use three extra attributes in the parameter array for the notification:
* '''header''': the content for this parameter displays before the table (also, the html will be parsed and player names will be colored according to the current game colors).
* '''footer''': the content for this parameter displays after the table (no parsing for coloring the player names)
* '''closing''': if this parameter is used, a button will be displayed with this label at the bottom of the popup and will allow players to close it (more easily than by clicking the top right 'cross' icon).

<pre>
$this->notifyAllPlayers( "tableWindow", '', [
"id" => 'finalScoring',
"title" => clienttranslate("Title of the scoring dialog"),
"table" => $table,
"header" => ['str' => clienttranslate('Table header with parameter ${number}'),
'args' => [ 'number' => 3 ],
],
"footer" => '<div class="myfoot"></div>',
"closing" => clienttranslate( "Closing button label" )
] );
</pre>

Note: currently id is not used - so you cannot access resulting div by id on js side
Note: any traslatable stirng have to be wrapped by clienttranslate() on top level OR it has to be recursive template.

DO NOT DO THIS:
<pre>
"footer" => '<div>'.clienttranslate( "The end" ).'</div>', // this will not work for translations!!!
</pre>

=== Scoring animated display ===

Sometimes, you may want to display a score value over an element to make the scoring easier to follow for the players (Terra Mystica final scoring for example).
You can do it with:

'''this.displayScoring(anchor_id: string, color: string, score: number | string, duration?: number, offset_x?: number, offset_y?: number): void'''

'''anchor_id''': ID of the html element to place the animated score onto (without the '#')

'''color''': hexadecimal RGB representation of the color (should be the color of the scoring player), but without a leading '#'. For instance, 'ff0000' for red.

'''score''': numeric score to display, prefixed by a '+' or '-'

'''duration''': animation duration in milliseconds (optional, default is 1000)

'''offset_x''' and '''offset_y''': if both offset_x and offset_y are defined and not null, apply the following offset (in pixels) to the scoring animation.
Note that the score is centered in the anchor, so the offsets might have to be negative if you calculate the position.

Note: if you want to display successively each score, you can use ''this.notifqueue.setSynchronous()'' function.
<pre>
setupNotifications: function() {
dojo.subscribe( 'displayScoring', this, "notif_displayScoring" );
...
}
...

notif_displayScoring: function(notif) {
const duration = notif.args.duration?notif.args.duration:1000;
this.notifqueue.setSynchronous('displayScoring', duration );
this.displayScoring( notif.args.target, notif.args.color, notif.args.score, duration);
},
</pre>

=== Speech bubble ===

For better interactivity in some games (Love Letter for example), you may use comic book style speech bubbles to express the players voices.
This is done with showBubble:

'''this.showBubble(anchor_id: string, text: string, delay?: number, duration?: number, custom_class?: string): void'''

* anchor_id - where to attach the bubble
* text - what to put in bubble, can be html
* delay - delay in milliseconds (optional, default 0)
* duration - duration of animation in milliseconds (optional, default 3000)
* custom_class - extra class to add to bubble (optional), if you need to override the default bubble style

<pre>
this.showBubble('meeple_2', _('Hello'), 0, 1000, 'pink_bubble');
</pre>

<pre>
notif_speechBubble(notif) {
var html = this.format_string_recursive(notif.args.text, notif.args.args);
this.showBubble(notif.args.target, html, notif.args.delay ?? 0, notif.args.duration ?? 1000);
},
</pre>

'''Warning''': if your bubble could overlap other active elements of the interface (buttons in particular), as it stays in place even after disappearing, you should use a custom class to give it the style "pointer-events: none;" in order to intercept click events.

Note: If you want this visually, but want to take complete control over this bubble and its animation (for example to make it permanent) you can just use div with 'discussion_bubble' class on it, and content of div is what will be shown.

== Translations ==

See [[Translations]]

== Players panels ==

=== Update players score ===

The column player_score from the player table is automatically loaded into this.scoreCtrl and therefore into the stars location on the player board. This occurs sometime after the game setup() function. However this score must be updated as the game progresses using notifications.

Note: this.scoreCtrl[player_id] is object of class [[Counter]], you can use other counter API.

Increase a player score (with a positive or negative number):

<pre>
this.scoreCtrl[ player_id ].incValue( score_delta );
</pre>

Set a player score to a specific value:

<pre>
this.scoreCtrl[ player_id ].setValue( new_score );
</pre>

Set a player score to a specific value with animation:

<pre>
this.scoreCtrl[ player_id ].toValue( new_score );
</pre>

Typical usage would be (that will process 'score' notification):
<pre>
setupNotifications : function() {
...
dojo.subscribe('score', this, "notif_score");
},
notif_score: function(notif) {
this.scoreCtrl[notif.args.player_id].setValue(notif.args.player_score);
},
</pre>

=== Adding stuff to player's panel ===

At first, create a new "JS template" string in your template (tpl) file:

(from Gomoku example)
<pre>
var jstpl_player_board = '\<div class="cp_board">\
<div id="stoneicon_p${id}" class="gmk_stoneicon gmk_stoneicon_${color}"></div><span id="stonecount_p${id}">0</span>\
</div>';
</pre>

Then, you add this piece of code in your JS file to add this template to each player panel:

<pre>
// Setting up player boards
for( var player_id in gamedatas.players )
{
var player = gamedatas.players[player_id];

// Setting up players boards if needed
var player_board_div = $('player_board_'+player_id);
dojo.place( this.format_block('jstpl_player_board', player ), player_board_div );
}
</pre>

(Note: the code above is of course from your "setup" function in your Javascript).

Very often, you have to distinguish current player and others players. In this case, you just have to create another JS template (ex: jstpl_otherplayer_board) and use it when "player_id" is different than "this.player_id".

=== Fixing Player Panel heights ===

You may find that the player panels don't automatically resize when adding something to (or removing something from) a player panel while the display is in portrait mode (i.e. the player summary panels are at the top of the screen rather than down the right side).

When this happens, call <pre>this.adaptPlayersPanels();</pre> This recalculates the layout and also adjusts the position of the actionbar for you.

=== Player's panel disabling/enabling ===

'''this.disablePlayerPanel(player_id: number): void'''

Disable given player panel (the panel background become gray).

Usually, this is used to signal that this played passes, or will be inactive during a while.

Note that the only effect of this is visual. There are no consequences on the behaviour of the panel itself.

'''this.enablePlayerPanel(player_id:number): void'''

Enable a player panel that has been disabled before.

'''this.enableAllPlayerPanels(): void'''

Enable all player panels that has been disabled before.

=== Player order ===

'''this.updatePlayerOrdering(): void'''

This function makes sure that player order in player's panel matches this.gamedatas.playerorder and its normally called by framework.
You can call it yoursel if you change this.gamedatas.playerorder from notification.
Also you can override this function to change defaults OR insert a non-player panel [[BGA_Studio_Cookbook#Inserting_non-player_panel]].

=== Counters ===
Note: there is bga component called "ebg/counter" this API is not using it, these methods
below declared right in core game. If you need animation for counters use ebg/counter

To use this API just create a counter dom element like this (class does not really matter)
<pre>
<div class="counter" id="bread"></div>
<div class="counter" id="coin"></div>
</pre>
The "bread" will the counter name.

The php code should send all "counters" data from getAllDatas() method like this

game.php
<pre>
protected function getAllDatas() {
// (the key must match counter_name)
$result['counters']=[
'bread' => [
'counter_name' => 'bread',
'counter_value' => 3
],
'coin' => [
'counter_name' => 'coin',
'counter_value' => 5
]
];
return $result;
}
</pre>

'''setCounter(counter_name: stirng, new_value: string | number): void'''

updates the global this.gamedatas.counters and value of node $(counter_name)
<pre>
notif_counter: function(notif) {
this.setCounter(notif.args.counter_name, notif.args.counter_value);
},
</pre>

'''incCounter(counter_name: string, delta: number): void'''
<pre>
notif_counter : function(notif) {
this.incCounter(notif.args.counter_name, notif.args.inc);
},
</pre>

'''updateCounters(counters: object): void'''

Useful for updating game counters in the player panel (such as resources).
'counters' arg is map of counters (the key must match counter_name)
{
'bread': {
'counter_name' : 'bread',
'counter_value' => 3
},
'coin': {
'counter_name' : 'coin',
'counter_value' => 5
}
}
All counters MUST be referenced in this.gamedatas.counters (means they should be send from php) and will be updated.
DOM objects referenced by 'counter_name' will have their innerHTML updated with 'counter_value'.

Usually you call this from notification

<pre>
notif_counter : function(notif) {
this.updateCounters(notif.args.counters);
},
</pre>

== BGA GUI components ==

BGA framework provides some useful ready-to-use components for the game interface:

[[Studio#BGA_Studio_game_components_reference]]

Note that each time you are using an additional component, you must declare it at the top of your Javascript file in the list of modules used.

Example if you are using "ebg.stock":
<pre>
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/stock" /// <=== we are using ebg.stock module
],
</pre>

== BGA Buttons ==

=== Basic Button ===

'''this.addActionButton(id: string, label: string, method: string | eventhandler, destination?: string, blinking?: boolean, color?: string): void'''

You can use this method to add an action button in the main action status bar (or other places).

Arguments:
* id: an element ID that should be unique in your HTML DOM document.
* label: the text of the button. Should be translatable (use _() function). Note: this can also be any html, such as "<div class='brick'></div>", see example below on how to make image action buttons.
* method: the name of your method that must be triggered when the player clicks on this button (can be name of the method on game class or handler).
* destination (optional): id of parent on where to add button, ONLY use in rare cases if location is not action bar. Use '''null''' as value if you need to specify other arguments.
* blinking (optional): if set to '''true''', the button is going blink to catch player's attention. Please DO NOT abuse blinking button. If you need button to blink after some time passed add class 'blinking' to the button later.
* color: could be '''blue''' (default), '''red''','''gray''' or '''none'''.

You should only use this method in your "onUpdateActionButtons" method. Usually, you use it like this:

<pre>
onUpdateActionButtons: function( stateName, args ) {
if (this.isCurrentPlayerActive()) {
switch( stateName ) {
case 'giveCards':
this.addActionButton( 'giveCards_button', _('Give selected cards'), 'onGiveCards' );
this.addActionButton( 'pass_button', _('Pass'), () => this.bgaPerformAction('actPass') );
break;
}
}
},
</pre>

In the example above, we are adding a "Give selected cards" button in the case we are on game state "giveCards". When player clicks on this button, it triggers our "onGiveCards" method.

Example using blinking red button:
<pre>
this.addActionButton( 'button_confirm', _('Confirm?'), 'onConfirm', null, true, 'red');
</pre>

If you want to call the handler with arguments, you can use arrow functions, like this:
<pre>
this.addActionButton( 'commit_button', _('Confirm'), () => this.onConfirm(this.selectedCardId), null, false, 'red');
</pre>

=== Image Button ===

You can use the same method, but add extra class to a button to disable the padding and style it, i.e.
<pre>
this.addActionButton( 'button_brick', '<div class="brick"></div>', ()=>{... on brick ...}, null, null, 'gray');
dojo.addClass('button_brick','bgaimagebutton');
</pre>

where

<pre>
.bgaimagebutton {
padding: 0px 12px;
min-height: 28px;
border: none;
}
</pre>

If you use this a lot, you can define a helper function, i.e.
<pre>
/**
* This method can be used instead of addActionButton, to add a button which is an image (i.e. resource). Can be useful when player
* need to make a choice of resources or tokens.
*/
addImageActionButton: function(id, div, handler, bcolor, tooltip) {
if (typeof bcolor == "undefined") {
bcolor = "gray";
}
// this will actually make a transparent button id color = gray
this.addActionButton(id, div, handler, null, false, bcolor);
// remove border, for images it better without
dojo.style(id, "border", "none");
// but add shadow style (box-shadow, see css)
dojo.addClass(id, "shadow bgaimagebutton");
// you can also add additional styles, such as background
if (tooltip) {
dojo.attr(id, "title", tooltip);
}
return $(id);
},
</pre>

=== Disabling Button ===

You can disable the '''bgabutton''' by adding the css class '''disabled''' in you js. The disabled button is still visible but is grey and not clickable.
For example in the '''onUpdateActionButtons''' :
<pre>
this.addActionButton('play_button_id', _('Play 1 to 3 cards'), 'playFunctionButton');
if (condition) {
dojo.addClass('play_button_id', 'disabled');
}
</pre>

=== Custom Buttons ===

You can create a custom button, but the BGA framework provides a standard button that requires only .css classes: '''bgabutton''' and '''bgabutton_${color}'''.

'''Examples:'''

<pre>
<a href="#" id="my_button_id" class="bgabutton bgabutton_blue"><span>My blue button</span></a>

<a href="#" id="my_button_id" class="bgabutton bgabutton_red bgabutton_big"><span>My big red button</span></a>
</pre>

'''Note''': To see it in action, check out ''Coloretto''.

=== Button outside of action bar ===

Use addActionButton() method with destination argument set
<pre>
this.addActionButton( 'commit_button', _('Confirm'), 'onConfirm', 'player_board', true, 'red');
</pre>

in example above the button will be place on object with id 'player_board'

== Image loading ==

See also [[Game_art:_img_directory]].

'''Be careful''': by default, ALL images of your img directory are loaded on a player's browser when he loads the game. For this reason, don't let in your img directory images that are not useful, otherwise it's going to slowdown the game load.

'''this.dontPreloadImage(image_file_name: string)'''

Using dontPreloadImage, you tell the interface to not preload a specific image in your img directory.

Example of use:
<pre>
this.dontPreloadImage( 'cards.png' );
</pre>

This is particularly useful if for example you have 2 different themes for a game. To accelerate the loading of the game, you can specify to not preload images corresponding to the other theme.

Another example of use: in "Gosu" game with Kamakor extension, you play with 5 sets of cards among 10 available. Cards images are organized by sets, and we only preload the images corresponding to the 5 current sets with '''ensureSpecificGameImageLoading( image_file_names_array )'''.
<pre>
// By default, do not preload anything
this.dontPreloadImage( 'cards.png' );
this.dontPreloadImage( 'clan1.png' );
this.dontPreloadImage( 'clan2.png' );
this.dontPreloadImage( 'clan3.png' );
this.dontPreloadImage( 'clan4.png' );
this.dontPreloadImage( 'clan5.png' );
this.dontPreloadImage( 'clan6.png' );
this.dontPreloadImage( 'clan7.png' );
this.dontPreloadImage( 'clan8.png' );
this.dontPreloadImage( 'clan9.png' );
this.dontPreloadImage( 'clan10.png' );
var to_preload = [];
for( i in this.gamedatas.clans )
{
var clan_id = this.gamedatas.clans[i];
to_preload.push( 'clan'+clan_id+'.png' );
}

this.ensureSpecificGameImageLoading( to_preload );

</pre>

'''Note:''' You don't need to specify to not preload game box images (game_box.png, game_box75.png...) since they are not preloaded by default.

'''this.ensureSpecificGameImageLoading(list: string[])'''

This is oppostive of dontPreloadImage - its ensure specific images is loaded. Note: only makes sense if preload list is empty, otherwise everything is loaded anyway

'''load specific images'''
All images that will be preloaded stored in g_img_preload. If you want to override it directly - there is no API, but you can do this in GAME constructor

g_img_preload = ['tokens.png', 'trains.png', 'loc_plan.png', 'eng.png', 'eng-back.png'];

You can also set it to empty array and call ensureSpecificGameImageLoading() on specific images

== Sounds ==

Add a custom sound and make it load with your interface:

Add this in your template (.tpl) file:
<pre>
<audio id="audiosrc_<gamename>_<yoursoundname>" src="{GAMETHEMEURL}img/<gamename>_<yoursoundname>.mp3" preload="none" autobuffer></audio>
<audio id="audiosrc_o_<gamename>_<yoursoundname>" src="{GAMETHEMEURL}img/<gamename>_<yoursoundname>.ogg" preload="none" autobuffer></audio>
</pre>

Note: this is a requirement to provide both a mp3 and a ogg file with the names <code><gamename>_<yoursoundname>[.ogg][.mp3]</code>.

Play the sound (from your .js file):

<pre>
playSound('<gamename>_<yoursoundname>'); // do not add 'this.' - its a global function
</pre>

Disable the standard "move" sound for this move (to replace it with your custom sound):

Add this to your notification handler:

<pre>
this.disableNextMoveSound();
</pre>

Note: it only disable the sound for the next move.

== Title bar and states ==

=== Client states ===

Client states is a way to simulate the state transition but without actually going
to server. It is usefull when you need to ask user multiple questions before you
send things to server

'''this.setClientState(newState: string, args: object)'''

Example:
this.setClientState("client_playerPicksLocation", {
descriptionmyturn : _("${you} must select location"),
});

For more information see [[BGA_Studio_Cookbook#Multi_Step_Interactions:_Select_Worker.2FPlace_Worker_-_Using_Client_States]]

'''this.restoreServerGameState()'''
If you are in client state it will restore the current server state (cheap undo)

'''this.on_client_state'''
Boolean indicating that we are in client state

=== Title bar ===
If you simply want to show something in title bar you can do it directly
$('pagemaintitletext').innerHTML = text;

This however will not work with parameters and will not draw You in color,
if you want to do proper args rendering use method below

;'''this.removeActionButtons()'''
Removes all buttons from title bar

;'''this.updatePageTitle()'''
:This function allows to update the current page title and turn description according to the game state arguments. If the current game state description this.gamedatas.gamestate.descriptionmyturn is modified before calling this function it allows to update the turn description without changing state. This will handle arguments substitutions properly.

Note: this functional also will calls this.onUpdateActionButtons, if you want different buttons then state defaults, use method in example to replace them, if it becomes too clumsy use client states (see above)

Example from Terra Mystica:
<pre>
onClickFavorTile: function( evt ) {
...
if ( ... ) {
this.gamedatas.gamestate.descriptionmyturn = _('Special action: ') + _('Advance 1 space on a Cult track');
this.updatePageTitle();
this.removeActionButtons();
this.addActionButton( ... );
...
return;
}
...

}
</pre>

== User preferences ==
'''this.getGameUserPreference(pref_id)'''

Return the value of a user preference. It will return the value currently selected in the select combo box, in the top-right menu.

'''this.setGameUserPreference(pref_id, value)'''

Programmatically change a user preference. It will have the same effect as if the player changed the value in the select combo box, in the top-right menu.

'''this.onGameUserPreferenceChanged'''

A callback you can define if you want to be notified when a user changes a user preference.

Example:<pre>
onGameUserPreferenceChanged: function(pref_id, pref_value) {
switch (pref_id) {
case 201:
document.getElementsByTagName('html')[0].classList.toggle('dark-background', pref_value == 2);
break;
}
}
</pre>

== Other useful stuff ==

'''dojo.hitch'''

With dojo.hitch, you can create a callback function that will run with your game object context whatever happen.

Typical example: display a BGA confirmation dialog with a callback function created with dojo.hitch:

<pre>
this.confirmationDialog( _('Are you sure you want to make this?'), dojo.hitch( this, function() {
this.bgaPerformAction('makeThis');
} ) );
</pre>

In the example above, using dojo.hitch, we ensure that the "this" object will be set when the callback is called.

NOTE: In modern JS there are lambdas that eliminate need for that, the example above will look like this
<pre>
this.confirmationDialog( _('Are you sure you want to make this?'), () => this.bgaPerformAction( 'makeThis') );
</pre>

;'''onScreenWidthChange()'''
:This function can be overridden in your game to manage some resizing on the client side when the browser window is resized. This function is also triggered at load time, so it can be used to adapt to the :viewport size at the start of the game too.

; this.bRealtime
: Return true if the game is in realtime. Note that having a distinct behavior in realtime and turn-based should be exceptional.

; g_replayFrom
: Global contains replay number in live game, it is set to undefined (i.e. not set) when it is not a replay mode, so consequentially the good check is '''typeof g_replayFrom != 'undefined'''' which returns true if the game is in replay mode <i>during the game</i> (the game is ongoing but the user clicked "replay from this move" in the log)

; g_archive_mode
: Returns true if the game is in archive mode <i>after the game</i> (the game has ended)

; this.instantaneousMode
: Returns true during replay/archive mode if animations should be skipped. Only needed if you are doing custom animations. (The BGA-provided animation functions like <i>this.slideToObject()</i> automatically handle instantaneous mode.)
: Technically, when you click "replay from move #20", the system replays the game from the very beginning with moves 0 - 19 happening in instantaneous mode and moves 20+ happening in normal mode.

; g_tutorialwritten
: Returns an object like the below if the game is in tutorial mode, or undefined otherwise. Tutorial mode is a special case of archive mode where comments have been added to a previous game to teach new players the rules.
{
author: "91577332",
id: "576",
mode: "view"
status: "alpha"
version_override: null
viewer_id: "84554161"
}

'''getBgaEnvironment(): string'''
: Returns "studio" for studio and "prod" for production environment (i.e. where games current runs). Only useful for debbugging hooks.
Note: alpha server is also "prod"

[[Category:Studio]]

BGA Studio Cookbook

2024-09-24T14:41:22Z

Sguzzer Gunayer: /* Action Stack - Using Client States */

This page is a cookbook of design and implementation recipes for BGA Studio framework.
For tooling and usage recipes see [[Tools and tips of BGA Studio]].
If you have your own recipes feel free to edit this page.

__TOC__

== Visual Effects, Layout and Animation ==

=== DOM manipulatons ===

==== Create pieces dynamically (using template) ====

'''Ingredients:''' ggg_ggg.tpl, ggg.js

Note: this method is recommended by BGA guildlines

Declared js template with variables in .tpl file, like this
<pre>
<script type="text/javascript">
// Javascript HTML templates
var jstpl_ipiece = '<div class="${type} ${type}_${color} inlineblock" aria-label="${name}" title="${name}"></div>';
</script>
</pre>

Use it like this in .js file
div = this.format_block('jstpl_ipiece', {
type : 'meeple',
color : 'ff0000',
name : 'Bob',
});

Then you do whatever you need to do with that div, this one specifically design to go to log entries, because it has embedded title (otherwise its a picture only) and no id.

Note: you could have place this variable in js itself, but keeping it in .tpl allows you to have your js code be free of HTML. Normally it never happens but
it is good to strive for it.
Note: you can also use string concatenation, its less readable. You can also use dojo dom object creation api's but its brutally verbose and its more unreadable.

==== Create pieces dynamically (using string concatenation) ====

'''Ingredients:''' ggg.js

<pre>
div = "<div class='meeple_"+color+"'></div>";
</pre>

or modern way

<pre>
div = `<div class='meeple_${color}'></div>`;
</pre>

==== Create all pieces statically ====

'''Ingredients:''' ggg_ggg.tpl, ggg.css, ggg.view.php (optional)

* Create ALL game pieces in html template (.tpl)
* ALL pieces should have unique id, and it should be meaningful, i.e. meeple_red_1
* Do not use inline styling
* Id of player's specific pieces should use some sort of 'color' identification, since player id cannot be used in static layout, you can use english color name, hex 6 char value, or color "number" (1,2,3...)
* Pieces should have separated class for its color, type, etc, so it can be easily styled in groups. In example below you now can style all meeples, all red meeples or all red tokens, or all "first" meeples

ggg.tpl:
<pre>
<div id="home_red" class="home_red home">
<div id="meeple_red_1" class="meeple red n1"></div>
<div id="meeple_red_2" class="meeple red n2"></div>
</div>
</pre>

ggg.css:

<pre>
.meeple {
width: 32px;
height: 39px;
background-image: url(img/78_64_stand_meeples.png);
background-size: 352px;
}

.meeple.red {
background-position: 30% 0%;
}
</pre>

* There should be straight forward mapping between server id and js id (or 1:1)
* You place objects in different zones of the layout, and setup css to take care of layout

<pre>
.home .meeple{
display: inline-block;
}
</pre>
* If you need to have a temporary object that look like original you can use dojo.clone (and change id to some temp id)
* If there is lots of repetition or zone grid you can use template generator, but inject style declaration in css instead of inline style for flexibility

Note:
* If you use this model you cannot use premade js components such as Stock and Zone
* You have to use alternative methods of animation (slightly altered) since default method will leave object with inline style attributes which you don't need

==== Use player color in template ====

'''Ingredients:''' ggg_ggg.tpl, ggg.view.php

.view.php:
<pre>
function build_page($viewArgs) {
// Get players & players number
$players = $this->game->loadPlayersBasicInfos();
$players_nbr = count($players);
/**
* ********* Place your code below: ***********
*/

// Set PCOLOR to the current player color hex
global $g_user;
$cplayer = $g_user->get_id();
if (array_key_exists($cplayer, $players)) { // may be not set if spectator
$player_color = $players [$cplayer] ['player_color'];
} else {
$player_color = 'ffffff'; // spectator
}
$this->tpl ['PCOLOR'] = $player_color;
</pre>

=== Status bar ===

==== Changing state prompt ====

State prompt is message displayed for player which usually comes from state description.
Sometimes you want to change it without changing state (one way is change state but locally, see client states above).

Simple way just change the html
<pre>
setMainTitle: function(text) {
$('pagemaintitletext').innerHTML = text;
},
// usage
onMeeple: function(event) {
//...
this.setMainTitle(_('You must select where meeple is going'));
},
</pre>

This however will not work with parameters and will not draw You in color, if you want this its more sophisticated:

<pre>
setDescriptionOnMyTurn : function(text) {
this.gamedatas.gamestate.descriptionmyturn = text;
var tpl = dojo.clone(this.gamedatas.gamestate.args);
if (tpl === null) {
tpl = {};
}
var title = "";
if (this.isCurrentPlayerActive() && text !== null) {
tpl.you = this.divYou();
}
title = this.format_string_recursive(text, tpl);

if (!title) {
this.setMainTitle(" ");
} else {
this.setMainTitle(title);
}
},
</pre>

Note: this method uses '''setMainTitle''' defined above and '''divYou''' defined in another section of this wiki.

=== Animation ===

==== Attach to new parent without destroying the object ====

BGA function attachToNewParent for some reason destroys the original, if you want similar function that does not you can use this
ggg.js

<pre>
/**
* This method will attach mobile to a new_parent without destroying, unlike original attachToNewParent which destroys mobile and
* all its connectors (onClick, etc)
*/
attachToNewParentNoDestroy: function (mobile_in, new_parent_in, relation, place_position) {

const mobile = $(mobile_in);
const new_parent = $(new_parent_in);

var src = dojo.position(mobile);
if (place_position)
mobile.style.position = place_position;
dojo.place(mobile, new_parent, relation);
mobile.offsetTop;//force re-flow
var tgt = dojo.position(mobile);
var box = dojo.marginBox(mobile);
var cbox = dojo.contentBox(mobile);
var left = box.l + src.x - tgt.x;
var top = box.t + src.y - tgt.y;

mobile.style.position = "absolute";
mobile.style.left = left + "px";
mobile.style.top = top + "px";
box.l += box.w - cbox.w;
box.t += box.h - cbox.h;
mobile.offsetTop;//force re-flow
return box;
},
</pre>

==== Animation on oversurface ====
If you use non-absolute position for your game elements (i.e you use layouts) - you cannot really use BGA animation functions. After years of fidding with different options I use
techique which I call animation on oversurface that works when parents use different zoom, rotation, etc

* You need another layer on top of everything - oversurface
* We create copy of the object on oversurface - to move
* We move the real object on final position - but make it invisible for now
* We move the phantom to final position applying required zoom and rotation (using css animation), then destroy it
* When animation is done we make original object visible in new position

The code is bit complex it can be found here

https://codepen.io/VictoriaLa/pen/gORvdJo

Game using it: century, ultimaterailroads

==== Scroll element into view ====
Ingredients: game.js

This function will scroll given node (div) into view and respect replays and archive mode

<pre>
scrollIntoViewAfter: function (node, delay) {
if (this.instantaneousMode || this.inSetup) {
return;
}
if (typeof g_replayFrom != "undefined") {
$(node).scrollIntoView();
return;
}
if (!delay) delay = 0;
setTimeout(() => {
$(node).scrollIntoView({ behavior: "smooth", block: "center" });
}, delay);
},
</pre>

=== Logs ===

==== Inject icon images in the log ====

Here is an example of what was done for Terra Mystica which is simple and straightforward:

<pre>
//Define the proper message
$message = clienttranslate('${player_name} gets ${power_income} via Structures');
if ($price > 0) {
$this->DbQuery("UPDATE player SET player_score = player_score - $price WHERE player_id = $player_id");
$message = clienttranslate('${player_name} pays ${vp_price} and gets ${power_income} via Structures');
}

// Notify
$this->notifyAllPlayers( "powerViaStructures", $message, array(
'i18n' => array( ),
'player_id' => $player_id,
'player_name' => $this->getUniqueValueFromDb( "SELECT player_name FROM player WHERE player_id = $player_id" ),
'power_tokens' => $power_tokens,
'vp_price' => $this->getLogsVPAmount($price),
'power_income' => $this->getLogsPowerAmount($power_income),
'newScore' => $this->getUniqueValueFromDb( "SELECT player_score FROM player WHERE player_id = $player_id" ),
'counters' => $this->getGameCounters(null),
) );
</pre>

With some functions to have the needed html added inside the substitution variable, such as:

<pre>
function getLogsPowerAmount( $amount ) {
return "<div class='tmlogs_icon' title='Power'><div class='power_amount'>$amount</div></div>";
}
</pre>
Note: injecting html from php is not ideal but easy, if you want more clean solution, use method below but it is a lot more sophisticated.

==== Inject images and styled html in the log ====

{{InfoBox|title=Warning — Translation|maxWidth=500|color=#c00|body='''In order to prevent interference with the translation process, keep in mind that you must only apply modifications to the args object, and not try to substitute the keys (the <code>${player_name}</code> parts of your string) in the log string.'''}}

So you want nice pictures in the game log. What do you do? The first idea that comes to mind is to send html from php in notifications (see method above).

This is a bad idea for many reasons:

* It's bad architecture. ui elements leak into the server, and now you have to manage the ui in multiple places.
* If you decided to change something in the ui in future version, replay logs for old games and tutorials may not work, since they use stored notifications.
* Log previews for old games become unreadable. (This is the log state before you enter the game replay, which is useful for troubleshooting and game analysis.)
* It's more data to transfer and store in the db.
* It's a nightmare for translators.

So what else can you do? You can use client side log injection to intercept log arguments (which come from the server) and replace them with html on the client side. Here are three different method you can use to achieve this.

===== Override <code>this.format_string_recursive()</code> method =====

'''Ingredients:''' ggg.js, ggg.game.php

I use this recipe for '''client side log injection''' to intercept log arguments (which come from the server) and replace them with html on the client side.

[[File:clientloginjection.png|left]]

ggg.js

<pre>

/** Override this function to inject html into log items. This is a built-in BGA method. */

/* @Override */
format_string_recursive : function format_string_recursive(log, args) {
try {
if (log && args && !args.processed) {
args.processed = true;

// list of special keys we want to replace with images
var keys = ['place_name','token_name'];

for ( var i in keys) {
var key = keys[i];
key in args && args[key] = this.getTokenDiv(key, args);

}
}
} catch (e) {
console.error(log,args,"Exception thrown", e.stack);
}
return this.inherited({callee: format_string_recursive}, arguments);
},
</pre>

'''Important:''' In the ''format_string_recursive'' method, the 'args' parameter will only contain arguments passed to it from the notify method in ggg.game.php (see below).

The 'log' parameter is the actual string that is inserted into the logs. You can perform additional js string manipulation on it.

<pre>
getTokenDiv : function(key, args) {
// ... implement whatever html you want here, example from sharedcode.js
var token_id = args[key];
var item_type = getPart(token_id,0);
var logid = "log" + (this.globalid++) + "_" + token_id;
switch (item_type) {
case 'wcube':
var tokenDiv = this.format_block('jstpl_resource_log', {
"id" : logid,
"type" : "wcube",
"color" : getPart(token_id,1),
});
return tokenDiv;

case 'meeple':
if ($(token_id)) {
var clone = dojo.clone($(token_id));

dojo.attr(clone, "id", logid);
this.stripPosition(clone);
dojo.addClass(clone, "logitem");
return clone.outerHTML;
}
break;

default:
break;
}

return "'" + this.clienttranslate_string(this.getTokenName(token_id)) + "'";
},
getTokenName : function(key) {
return this.gamedatas.token_types[key].name; // get name for the key, from static table for example
},
</pre>

Note that in this case the server simply injects token_id as a name, and the client substitutes it for the translated name or the picture.

ggg.game.php:

$this->notifyAllPlayers('playerLog',clienttranslate('Game moves ${token_name}'),['token_name'=>$token_id]);

'''Important:''' As noted above, only arguments actually passed by this method are available to the args parameter received in the client-side ''format_string_recursive'' method.

Sometimes it is the case that you want to pass arguments that are not actually included in the output message. For example, suppose we have a method like this:

$this->notifyAllPlayers('tokenPlaced',clienttranslate('Player placed ${token_name}'),array(
'token_name' => $token_id,
'zone_played' => $zone);

This will output "Player placed ${token_name}" in the log, and if we subscribe to a notification method activated by the "tokenPlaced" event in the client-side code, that method can make use of the 'zone_played' argument.

Now if you want to make some really cool things with game log, most probably you would need more arguments than are included in log message. The problem with that,
it will work at first, but if you reload game using F5 or when the game loads in turn based mode, you will loose your additional parameters, why? Because when game reloads it does not actually send same notifications, it sends special "hitstorical_log" notification where all parameters not listed in the message are removed. In example above, field zone_played would be removed from historical log as it is not included in message of the notification. You can till preserve specific arguments in historical log by adding special field preserve to notification arguments like this:

<pre>
$this->notifyAllPlayers('tokenPlaced',clienttranslate('Player placed ${token_name}'),array(
'token_name' => $token_id,
'zone_played' => $zone,
'preserve' => [ 'zone_played' ]
);
</pre>

Now you can use zone_played in format_string_recursive even in historical logs.

===== Use <code>:formatFunction</code> option provided by <code>dojo.string.substitute</code> =====

'''Ingredients:''' ggg.js, ggg.game.php, ggg_ggg.tpl, ggg.css

The above method will work in most of the cases, but if you use dotted keys such as <code>${card.name}</code> (which is supported by the framework, for private state args), the key won't be substituted because the <code>key in arg</code> test will fail. If so you need to rely either on this way, or the one after.

'''WARNING:''' using this method on an already advanced project will require you to go through all your notifications to change keys !

Under the hood, the '''this.format_string_recursive()''' function calls the '''dojo.string.substitute''' method which substitutes <code>${keys}</code> with the value provided. If you take a look at the [https://dojotoolkit.org/reference-guide/1.7/dojo/string.html#substitute documentation] and [https://github.com/dojo/dojo/blob/c3ceb017cfa25b703f5662dc83d1c8aae9bc5d81/string.js#L163 source code] you can notice that the key can be suffixed with a colon (<code>:</code>) followed by a function name. This will allow you to specify directly in the substitution string which keys need HTML injection.

First of all, you need to define your formatting function in the ggg.js file:
<pre>
[[ggg.js]]
getTokenDiv : function(value, key) {
//This is only an example implementation, you need to write your own.
//The method should return HTML code
switch (key) {
case 'html_injected_argument1':
return this.format_block('jstpl_HTMLLogElement1',{value: value});
case 'html_injected_argument2':
return this.format_block('jstpl_HTMLLogElement2',{value: value});
...
}
}
</pre>

Obviously you need to define the appropriate templates in the ggg_ggg.tpl file:
<pre>
[[ggg_ggg.tpl]]
let jstpl_HTMLLogElement1 = '<div class="log-element log-element-1-${value}"></div>';
let jstpl_HTMLLogElement2 = '<div class="log-element log-element-2-${value}"></div>';
...
</pre>
And the appropriate classes in ggg.css.

Then you need to add the <code>dojo/aspect</code> module at the top of the ggg.js file:

<nowiki>[[ggg.js]]</nowiki>
define([
"dojo", "dojo/_base/declare",
'''<span style="color:green;">"dojo/aspect",</span> //MUST BE IN THIRD POSITION''' (see [[#Including your own JavaScript module (II)|below]])
"ebg/core/gamegui",
"ebg/counter",
], function (dojo, declare, <span style="color:green;">'''aspect'''</span>) {
...

And you also need to add the following code in your <code>contructor</code> method in the ggg.js:

<nowiki>[[ggg.js]]</nowiki>
constructor: function(){

// ... skipped code ...
let gameObject = this; //Needed as the this object in aspect.before will not refer to the game object in which the formatting function resides
aspect.before(dojo.string, "substitute", function(template, map, transform) { //This allows you to modify the arguments of the dojo.string.substitute method before they're actually passed to it
return [template, map, transform, gameObject];
});

Now you're all set to inject HTML in your logs. To actually achieve this, you must specify the function name with the key like so:

<nowiki>[[ggg.game.php]]</nowiki>
$this->notifyAllPlayers("notificationName", clienttranslate("This log message contains ${plainTextArgument} and the following will receive HTML injection: ${html_injected_argument1:getTokenDiv}"), [
"plainTextArgument" => "some plain text here",
"html_injected_argument1" => "some value used by getTokenDiv",
]);

You're not limited writing only one function, you can write as many functions as you like, and have them each inject a specific type of HTML. You just need to specify the relevant function name after the column in the substitution key.

===== Use <code>transform</code> argument of <code>dojo.string.substitute</code> =====

'''Ingredients:''' ggg.js, ggg.game.php, ggg_ggg.tpl, ggg.css

This method is also relying on the use of <code>dojo.string.substitute</code> by the framework, and will use the <code>transform</code> argument, which, accordting to [https://github.com/dojo/dojo/blob/c3ceb017cfa25b703f5662dc83d1c8aae9bc5d81/string.js#L163 source code] and [https://dojotoolkit.org/reference-guide/1.7/dojo/string.html#substitute documentation] will be run on all the messages going through dojo.string.substitute.

'''WARNING:''' This method will be applied to all strings that go through dojo.string.substitute. As such you must take extra care not to substitute keys that may be used by the framework (i.e. ${id}). In order to do so, a good practise would be to prefix all keys that need substitution with a trigram of the game name.

Since all the keys will be fed to the tranform function, by default, it must return the value, substituted or not per your needs. You can define the function like this in the ggg.js file:

<nowiki>[[ggg.js]]</nowiki>
getTokenDiv : function(value, key) {
//This is only an example implementation, you need to write your own.
//The method should return HTML code
switch (key) {
case 'html_injected_argument1':
return this.format_block('jstpl_HTMLLogElement1',{value: value});
case 'html_injected_argument2':
return this.format_block('jstpl_HTMLLogElement2',{value: value});
...
default:
return value; //Needed otherwise regular strings won't appear since since the value isn't returned by the function
}
}

The templates must be defined in the ggg_ggg.tpl file and the corresponding CSS classes in the ggg.css file.

You need to add the following code at the beginning of the ggg.js file:

<nowiki>[[ggg.js]]</nowiki>
define([
"dojo", "dojo/_base/declare",
'''<span style="color:green;">"dojo/aspect",</span> //MUST BE IN THIRD POSITION''' (see [[#Including your own JavaScript module (II)|below]])
"ebg/core/gamegui",
"ebg/counter",
], function (dojo, declare, <span style="color:green;">'''aspect'''</span>) {
...

And the following code to the <code>constructor</code> method in ggg.js:

<nowiki>[[ggg.js]]</nowiki>
constructor: function(){
// ... skipped code ...
let transformFunction = dojo.hitch(this, "getTokenDiv"); //Needed as the this object in aspect.before will not refer to the game object in which the formatting function resides
aspect.before(dojo.string, "substitute", function(template, map, transform) {
if (undefined === transform) { //Check for a transform function presence, just in case
return [template, map, transformFunction];
}
});

Then you're all set for log injection, no need to change anything on the PHP side.

==== Processing logs on re-loading ====

You rarely need to process logs when reloading, but if you want to do something fancy you may have to do it after logs are loaded.
Logs are loaded asyncronously so you have to listen for logs to be fully loaded.
Unfortunately there is no direct way of doing it so this is the hack.

'''Hack alert''' - this extends undocumented function and may be broken when framework is updated

'''Ingredients:''' ggg.js

<pre>
/*
* [Undocumented] Override BGA framework functions to call onLoadingLogsComplete when loading is done
@Override
*/
setLoader: function(image_progress, logs_progress) {
this.inherited(arguments); // required, this is "super()" call, do not remove
//console.log("loader", image_progress, logs_progress)
if (!this.isLoadingLogsComplete && logs_progress >= 100) {
this.isLoadingLogsComplete = true; // this is to prevent from calling this more then once
this.onLoadingLogsComplete();
}
},

onLoadingLogsComplete: function() {
console.log('Loading logs complete');
// do something here
},
</pre>

=== Player Panel ===

==== Inserting non-player panel ====

'''Ingredients:''' ggg.js, ggg_ggg.tpl

If you want to insert non-player panel on the right side (for example to hold extra preferences, zooming controls, etc)

this can go pretty much anywhere in template it will be moved later

ggg_ggg.tpl:
<pre>
<div class='player_board_config' id="player_board_config">

<button id="zoom-out" class=" fa fa-search-minus fa-2x config-control"></button>
<button id="zoom-in" class=" fa fa-search-plus fa-2x config-control"></button>
<button id="show-settings" class="fa fa-cog fa-2x config-control "></button>
</div>
</pre>

some hackery required in js

ggg.js:
<pre>
/* @Override */
updatePlayerOrdering() {
this.inherited(arguments);
dojo.place('player_board_config', 'player_boards', 'first');
},
</pre>

=== Images and Icons ===

==== Accessing images from js ====

'''Ingredients:''' ggg.js

<pre>
// your game resources

var my_img = '<img src="'+g_gamethemeurl+'img/cards.jpg"/>';

// shared resources
var my_help_img = "<img class='imgtext' src='" + g_themeurl + "img/layout/help_click.png' alt='action' /> <span class='tooltiptext'>" +
text + "</span>";
</pre>

==== High-Definition Graphics ====

Some users will have screens which can display text and images at a greater resolution than the usual 72 dpi, e.g. the "Retina" screens on the 5k iMac, all iPads, and high-DPI screens on laptops from many manufacturers. If you can get art assets at this size, they will make your game look extra beautiful. You ''could'' just use large graphics and scale them down, but that would increase the download time and bandwidth for users who can't display them. Instead, a good way is to prepare a separate graphics file at exactly twice the size you would use otherwise, and add "@2x" at the end of the filename, e.g. if pieces.png is 240x320, then pieces@2x.png is 480x640.

There are two changes required in order to use the separate graphics files. First in your css, where you use a file, add a media query which overrides the original definition and uses the bigger version on devices which can display them. Ensuring that the "background-size" attribute is set means that the size of the displayed object doesn't change, but only is drawn at the improved dot pitch.
<pre>
.piece {
position: absolute;
background-image: url('img/pieces.png');
background-size:240px 320px;
z-index: 10;
}
@media (-webkit-min-device-pixel-ratio: 2), (min-device-pixel-ratio: 2), (min-resolution: 192dpi)
{
.piece {
background-image: url('img/pieces@2x.png');
}
}
</pre>

Secondly, in your setup function in javascript, you must ensure than only the appropriate one version of the file gets pre-loaded (otherwise you more than waste the bandwidth saved by maintaining the standard-resolution file). Note that the media query is the same in both cases:
<pre>
var isRetina = "(-webkit-min-device-pixel-ratio: 2), (min-device-pixel-ratio: 2), (min-resolution: 192dpi)";
if (window.matchMedia(isRetina).matches)
{
this.dontPreloadImage( 'pieces.png' );
this.dontPreloadImage( 'board.jpg' );
}
else
{
this.dontPreloadImage( 'pieces@2x.png' );
this.dontPreloadImage( 'board@2x.jpg' );
}
</pre>

==== Using CSS to create different colors of game pieces if you have only white piece ====

<pre>
background-color: #${color};
background-blend-mode: multiply;
background-image: url( 'img/mypiece.png');
mask: url('img/mypiece.png');
-webkit-mask: url('img/mypiece.png');
</pre>

where ${color} - is color you want

Note: piece has to be white (shades of gray). Sprite can be used too, just add add background-position as usual.

==== Accessing player avatar URLs ====

<pre>
getPlayerAvatar(playerId) {
let avatarURL = '';

if (null != $('avatar_' + playerId)) {
let smallAvatarURL = dojo.attr('avatar_' + playerId, 'src');
avatarURL = smallAvatarURL.replace('_32.', '_184.');
}
else {
avatarURL = 'https://x.boardgamearena.net/data/data/avatar/default_184.jpg';
}

return avatarURL;
},
</pre>

Note: This gets avatar URLs at 184x184 resolution. You can also use 92, 50, and 32 depending on which resolution you want.

==== Adding Image buttons ====

Its pretty trivial but just in case you need a working function:

ggg.js:
<pre>
addImageActionButton: function (id, div_html, handler) { // div_html is string not node
this.addActionButton(id, div_html, handler, '', false, 'gray');
dojo.style(id, "border", "none"); // remove ugly border
dojo.addClass(id, "bgaimagebutton"); // add css class to do more styling
return $(id); // return node for chaining
},

</pre>
Example of usage:
<pre>
this.addImageActionButton('button_coin',"<div class='coin'></div>", ()=>{ alert('Ha!'); });
</pre>

=== Other Fluff ===

==== Use thematic fonts ====

'''Ingredients:''' ggg.css

Sometime game elements use specific fonts of text, if you want to match it up you can load some specific font (IMPORTANT: from some '''free font''' source. See notes below).

[[File:Dragonline_font.png]]

.css
<pre>
/* latin-ext */
@font-face {
font-family: 'Qwigley';
font-style: normal;
font-weight: 400;
src: local('Qwigley'), local('Qwigley-Regular'), url(https://fonts.gstatic.com/s/qwigley/v6/2Dy1Unur1HJoklbsg4iPJ_Y6323mHUZFJMgTvxaG2iE.woff2) format('woff2');
unicode-range: U+0100-024F, U+1E00-1EFF, U+20A0-20AB, U+20AD-20CF, U+2C60-2C7F, U+A720-A7FF;
}
/* latin */
@font-face {
font-family: 'Qwigley';
font-style: normal;
font-weight: normal;
src: local('Qwigley'), local('Qwigley-Regular'), url(https://fonts.gstatic.com/s/qwigley/v6/gThgNuQB0o5ITpgpLi4Zpw.woff2) format('woff2');
unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02C6, U+02DA, U+02DC, U+2000-206F, U+2074, U+20AC, U+2212, U+2215, U+E0FF, U+EFFD, U+F000;
}
@font-face {
font-family: 'Qwigley';
font-style: normal;
font-weight: normal;
src: local('Qwigley'), local('Qwigley-Regular'), url(http://ff.static.1001fonts.net/q/w/qwigley.regular.ttf) format('ttf');
}

.zone_title {
display: inline-block;
position: absolute;
font: italic 32px/32px "Qwigley", cursive;
height: 32px;
width: auto;
}
</pre>

'''NB:''' if you need to include a font that's not available online, an extra action will be needed from an admin. Please include the font file(s) in your img directory, and mention it to admins when requesting your game to be moved to alpha. '''Please remember that the font has to be free, and include a .txt with all appropriate license information about the font.'''
You can look for free fonts (for example) on https://fonts.google.com or https://www.fontsquirrel.com/)

'''Content Security Policy'''

BGA runs a Content Security Policy which will limit the origins from which you can load external fonts, in order to prevent license abuse.

The CSP is a whitelist of allowed origins. To see the list, view the response headers of any page on Studio, and look for the "Content-Security-Policy" header.

You will specifically want to check for the font-src token within these headers, and limit any external fonts to these sources.

'''This list is subject to change''' but as of the time of writing, the only acceptabled external sites are use.typekit.net and fonts.gstatic.com.

=== Scale to fit for big boards ===

'''Ingredients:''' ggg_ggg.tpl, ggg.js

Lets say you have huge game board, and lets say you want it to be 1400px wide. Besides the board there will be side bar which is 240 and trim.
My display is 1920 wide so it fits, but there is big chance other people won't have that width. What do you do?

You have to decide:
* If board does not fit you want scale whole thing down, the best way is probably use viewport (see https://en.doc.boardgamearena.com/Your_game_mobile_version)
* You can leave the board as is and make sure it is scrollable horizonatally
* You add custom scale just for the board (can add user controls - and hook to transform: scale())

I tried to auto-scale but this just does work, too many variables - browser zoom, 3d mode, viewport, custom bga scaling, devicePixelRatio - all create some impossible coctail of zooming...
Here is scaling functing for custom user scaling

ggg_ggg.tpl:
<pre>
<div id="thething" class="thething">
... everything else you declare ...
</div>
</pre>

ggg.js:
<pre>
onZoomPlus: function() {
this.setZoom(this.zoom + 0.1);
},
onZoomMinus: function() {
this.setZoom(this.zoom - 0.1);
},

setZoom: function (zoom) {
zoom = parseInt(zoom) || 0;
if (zoom === 0 || zoom < 0.1 || zoom > 10) {
zoom = 1;
}
this.zoom = zoom;
var inner = document.getElementById("thething");

if (zoom == 1) {
inner.style.removeProperty("transform");
inner.style.removeProperty("width");
} else {
inner.style.transform = "scale(" + zoom + ")";
inner.style.transformOrigin = "0 0";
inner.style.width = 100 / zoom + "%";
}
localStorage.setItem(`${this.game_name}_zoom`, "" + this.zoom);
this.onScreenWidthChange();
},
</pre>

=== Dynamic tooltips ===

If you really need a dynamic tooltip you can use this technique. (Only use it if the static tooltips provided by the BGA framework are not sufficient.)

new dijit.Tooltip({
connectId: ["divItemId"],
getContent: function(matchedNode){
return "... calculated ...";
}
});

This is an out-of-the-box djit.Tooltip. It has a ''getContent'' method which is called dynamically.

The string returned by getContent() becomes the innerHTML of the tooltip, so it can be anything. In this example matchedNode is a dojo node representing dom object with id of "divItemId" but there are more parameters which I am not posting here which allows more sophisticated subnode queries (i.e. you can attach tooltip to all nodes with class or whatever).

[https://dojotoolkit.org/reference-guide/1.10/dijit/Tooltip.html dijit.Tooltip]

It's not part of the BGA API so use at your own risk.

=== Rendering text with players color and proper background ===

'''Ingredients:''' ggg.js

<pre>
/* Implementation of proper colored You with background in case of white or light colors */

divYou: function() {
var color = this.gamedatas.players[this.player_id].color;
var color_bg = "";
if (this.gamedatas.players[this.player_id] && this.gamedatas.players[this.player_id].color_back) {
color_bg = "background-color:#" + this.gamedatas.players[this.player_id].color_back + ";";
}
var you = "<span style=\"font-weight:bold;color:#" + color + ";" + color_bg + "\">" + __("lang_mainsite", "You") + "</span>";
return you;
},

/* Implementation of proper colored player name with background in case of white or light colors */

divColoredPlayer: function(player_id) {
var color = this.gamedatas.players[player_id].color;
var color_bg = "";
if (this.gamedatas.players[player_id] && this.gamedatas.players[player_id].color_back) {
color_bg = "background-color:#" + this.gamedatas.players[player_id].color_back + ";";
}
var div = "<span style=\"color:#" + color + ";" + color_bg + "\">" + this.gamedatas.players[player_id].name + "</span>";
return div;
},
</pre>

=== Cool realistic shadow effect with CSS ===

==== Rectangles and circles ====

It is often nice to have a drop shadow around tiles and tokens, to separate them from the table visually. It is very easy to add a shadow to rectangular elements, just add this to your css:

<pre>
.xxx-tile {
box-shadow: 3px 3px 3px #000000a0;
}
</pre>

box-shadow obeys '''border-radius''' of the element, so it will look good for rounded rectangles, and hence also circles (if border-radius is set appropriately).

box-shadow also supports various other parameters and can be used to achieve effects such as glowing, borders, inner shadows etc. If you need to animate a box-shadow, you may be able to get better performance (avoiding redraws) if you attach the shadow to another element (possibly an ::after pseudo-element) and change only the '''opacity''' of that element.

==== Irregular Shapes ====

If you wish to make a shadow effect for game pieces that are not a rectangle, but your game pieces are drawn from rectangles in a PNG image, you can apply the shadow to the piece using any art package and save it inside the image. This usually will yield the best performance. Remember to account for the size of the shadow when you lay out images in the sprite sheet.

However that sometimes will not be an option, for example if the image needs to be rotated while the shadow remains offset in the same direction. In this case, one option is to not use box-shadow but use filter, which is supported by recent major browsers. This way, you can use the alpha channel of your element to drop a shadow. This even work for transparent backgrounds, so that if you are using the "CSS-sprite" method, it will work!

For instance:

<pre>
.xxx-token {
filter: drop-shadow(0px 0px 1px #000000);
}
</pre>

Beware that some browsers still do not always draw drop-shadow correctly. In particular, Safari frequently leaves bits of shadow behind when objects move around the screen. In Chrome, shadows sometimes flicker badly if another element is animating close by. Some of these correctness issues can be solved by adding '''isolation: isolate; will-change: filter;''' to affected elements, but this significantly affects redraw performance.

Beware of performance issues - particularly on Safari (MacOS, iPhone and iPad). Keep in mind that drop-shadow are very GPU intensive. This becomes noticeable once you have about 40 components with drop-shadow filter. If that is your case, you can quite easily implement a user preference to disable shadows for users on slower machines:

gameoptions.inc.php
<pre>
100 => array(
'name' => totranslate('Shadows'),
'needReload' => true, // after user changes this preference game interface would auto-reload
'values' => array(
1 => array( 'name' => totranslate( 'Enabled' ), 'cssPref' => '' ),
2 => array( 'name' => totranslate( 'Disabled' ), 'cssPref' => 'no-shadow' )
)
),
</pre>

[game].css
<pre>
.no-shadow * {
filter: none !important;
}
</pre>For Safari, it is usually better to simply disable drop-shadow completely: [[Game interface stylesheet: yourgamename.css#Warning: using drop-shadow]].

==== Shadows with clip-path ====

For some reason, a shadow will not work together with clip-path on one element. To use both clip-path (when for example using .svg to cut out cardboard components from your .jpg spritesheet) and drop-shadow, you need to wrap the element into another one, and apply drop-shadow to the outer one, and clip-path to the inner one.

<pre>
<div class='my-token-wrap'>
<div class='my-token'>
</div>
</div>
</pre>
<pre>
.my-token-wrap {
filter: drop-shadow(0px 0px 1px #000000);
}
.my-token-wrap .my-token {
clip-path: url(#my-token-path);
}
</pre>

=== Using the CSS classes from the state machine ===

If you need to hide or show stuff depending on the state of your game, you can of course use javascript, but CSS is hand enough for that. The #overall-content element does change class depending on the game state. For instance, if you are in state ''playerTurn'', it will have the class ''gamestate_playerTurn''.

So now, if you want to show the discard pile only during player turns, you may use:

<pre>
#discard_pile { display: none }
.gamestate_playerTurn #discard_pile { display: block }
</pre>

This can be used if you want to change sizing of elements, position, layout or visual appearance.

== Game Model and Database design ==

=== Database for The euro game ===
Lets say we have a game with workers, dice, tokens, board, resources, money and vp. Workers and dice can be placed in various zones on the board, and you can get resources, money, tokens and vp in your home zone. Also tokens can be flipped or not flipped.

[[File:Madeira board.png]]

Now lets try to map it, we have
* (meeple,zone)
* (die, zone, sideup)
* (resource cube/money token/vp token,player home zone)
* (token, player home zone, flip state)
We can notice that resource and money are uncountable, and don't need to be track individually so we can replace our mapping to
* (resource type/money,player home zone, count)
And vp stored already for us in player table, so we can remove it from that list.

Now when we get to encode it we can see that everything can be encoded as (object,zone,state) form, where object and zone is string and state is integer. The resource mapping is slightly different semantically so you can go with two table, or counting using same table with state been used as count for resources.

So the piece mapping for non-grid based games can be in most case represented by (string: token_key, string: token_location, int: token_state), example of such database schema can be found here: [https://github.com/elaskavaia/bga-sharedcode/blob/master/dbmodel.sql dbmodel.sql] and class implementing access to it here [https://github.com/elaskavaia/bga-sharedcode/blob/master/modules/tokens.php table.game.php].

Variant 1: Minimalistic

CREATE TABLE IF NOT EXISTS `token` (
`token_key` varchar(32) NOT NULL,
`token_location` varchar(32) NOT NULL,
`token_state` int(10),
PRIMARY KEY (`token_key`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

{| class="wikitable"
|+token
! token_key
! token_location
! token_state
|-
|meeple_red_1
|home_red
|0
|-
|dice_black_2
|board_guard
|1
|-
|dice_green_1
|board_action_mayor
|3
|-
|bread
|home_red
|5
|}

Now how we represent resource counters such as bread?
Using same table from we simply add special counter token for bread and use state to indicate the count. Note to keep first column unique we have to add player identification for that counter, i.e. ff0000 is red player.

{| class="wikitable"
|+token
! token_key
! token_location
! token_state
|-
|bread_ff0000
|tableau_ff0000
|5
|}

See php module for this table here https://github.com/elaskavaia/bga-sharedcode/blob/master/modules/tokens.php

Variant 2: Additional resource table, resource count for each player id

CREATE TABLE IF NOT EXISTS `resource` (
`player_id` int(10) unsigned NOT NULL,
`resource_key` varchar(32) NOT NULL,
`resource_count` int(10) signed NOT NULL,
PRIMARY KEY (`player_id`,`resource_key`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

ALTER TABLE resource ADD CONSTRAINT fk_player_id FOREIGN KEY (player_id) REFERENCES player(player_id);

{| class="wikitable"
|+resource
! player_id
! resource_key
! resource_count
|-
|123456
|bread
|5
|}

Variant 3: More normalised

This version is similar to "card" table from hearts tutorial, you can also use exact cards database schema and Deck implementation for most purposes (even you not dealing with cards).

CREATE TABLE IF NOT EXISTS `token` (
`token_id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`token_type` varchar(16) NOT NULL,
`token_arg` int(11) NOT NULL,
`token_location` varchar(32) NOT NULL,
`token_state` int(10),
PRIMARY KEY (`token_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

{| class="wikitable"
|+token
! token_id
! token_type
! token_arg
! token_location
! token_state
|-
|22
|meeple
|123456
|home_123456
|0
|-
|23
|dice
|2
|board_guard
|1
|-
|26
|dice
|1
|board_action_mayor
|3
|-
|49
|bread
|0
|home_123456
|5
|}

Advantages of this would be is a bit more straightforward to do some queries in db, disadvantage its hard to read (as you can compare with previous example, you
cannot just look at say, ah I know what it means). Another questionable advantage is it allows you to do id randomisation, so it hard to do crafted queries to
cheat, the down side of that you cannot understand it either, and handcraft db states for debugging or testing.

=== Database for The card game ===

Lets say you have a standard card game, player have hidden cards in hand, you can draw card from draw deck, play card on tableau and discard to discard pile.
We have to design database for such game.

In real word to "save" the game we take a picture a play area, save cards from it, then put away draw deck, discard and hand of each player separately and mark it, also we will record current scoring (if any) and who's turn was it.

* Framework handles state machine transition, so you don't have to worry about database design for that (i.e. who's turn it is, what phase of the game we are at, you still have to design it but part of state machine step)
* Also framework supports basic player information, color, order around the table, basic scoring, etc, so you don't have to worry about it either
* The only thing you need in our database is state of the "board", which is "where each pieces is, and in what state", or (position,rotation) pair.

Lets see what we have for that:
* The card state is very simple, its usually "face up/face down", "tapped/untapped", "right side up/up side down"
* As position go we never need real coordinates x,y,z. We need to know what "zone" card was, and depending on the zone it may sometimes need an extra "z" or "x" as card order. The zone position usually static or irrelevant.
* So our model is: we have cards, which have some attributes, at any given point in time they belong to a "zone", and can also have order and state
* Now for mapping we should consider what information changes and what information is static, later is always candidate for material file
* For dynamic information we should try to reduce amount of fields we need
** we need at least a field for card, so its one
** we need to know what zone cards belong to, its 2
** and we have possibly few other fields, if you look closely at you game you may find out that most of the zone only need one attribute at a time, i.e. draw pile always have cards face down, hand always face up, also for hand and discard order does not matter at all (but for draw it does matter). So in majority of cases we can get away with one single extra integer field representing state or order
* In real database both card and zone will be integers as primary keys referring to additional tables, but in our case its total overkill, so they can be strings as easily

Variant 1: Minimalistic

<pre>
CREATE TABLE IF NOT EXISTS `card` (
`card_key` varchar(32) unsigned NOT NULL,
`card_location` varchar(32) NOT NULL,
`card_state` int(11) NOT NULL,
PRIMARY KEY (`card_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

Variant 2: More normalised

This version supported by Deck php class, so unless you want to rewrite db access layer go with this one

<pre>
CREATE TABLE IF NOT EXISTS `card` (
`card_id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`card_type` varchar(16) NOT NULL,
`card_type_arg` int(11) NOT NULL,
`card_location` varchar(16) NOT NULL,
`card_location_arg` int(11) NOT NULL,
PRIMARY KEY (`card_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

Note: if you using this schema, some zones/locations have special semantic. The 'hand' location is actually multiple locations - one per player, but player id is encoded as card_location_arg. If 'hand' in your game is ordered, visible or can have some other card states, you cannot use hand location (replacement is hand_<player_id> or hand_<color_id>)

== Code Organization ==

=== Including your own JavaScript module ===
'''Ingredients:''' ggg.js, modules/ggg_other.js

* Create ggg_other.js in modules/ folder and sync
<pre>
define([
"dojo", "dojo/_base/declare"
], function( dojo, declare )
{
return declare("bgagame.other", null, { // null here if we don't want to inherit from anything
constructor: function(){},
mystuff: function(){},
});

});

</pre>
* Modify ggg.js to include it

define([ "dojo", "dojo/_base/declare", "ebg/core/gamegui", "ebg/counter",
g_gamethemeurl + "modules/ggg_other.js" // load my own module!!!
], function(dojo,
declare) {

use it

foo = new bgagame.other();

=== Including your own JavaScript module (II) ===

* Create ggg_other.js in modules/ folder and sync

define([], function () {
return "value";
});

* Modify ggg.js to include it

define([
"dojo",
"dojo/_base/declare",
"bgagame/modules/ggg_other",
"ebg/core/gamegui",
"ebg/counter"
], function(dojo, declare, other) {

});

This is maybe a little bit more the idea of the AMD Loader than the first option, although the first option should work as well.

A little explanation to this:
The define function loads all the modules listed in the array and calls the following function with these loaded modules as parameters.
By putting your module at the third position in the array it is passed as the third parameter to the function. Be aware that the modules are resolved by position only, not by name. So you can load the module '''ggg_other''' and pass it as a parameter with the name '''other'''. '''gamegui''' and '''counter''' are passed in as well, but when the parameters are not defined they are just skipped. Because these modules put their content into the global scope it does not matter and you can use them from there.

In the example above the string "value" is passed for the parameter '''other''', but the function in your module can return whatever you want. It can be an object, an array, something you declared with dojo.declare, you can return even functions.
Your module can load other modules. Just put them in the array at the beginning and pass them as parameters to your function.
The advantage of passing the values as parameter is that you do not need to put these values in the global scope, so they can't be collisions with values defined in other scripts or the BGA Framework.

The dojo toolkit provides good documentation to all of its components, the complete documentation for the AMD-Loader is here:
https://dojotoolkit.org/documentation/tutorials/1.10/modules/index.html It should be still correct, even as it seems to be only for version 1.10

=== Including your own PHP module ===
'''Ingredients:''' ggg.game.php, modules/ggg_other.php

* Create ggg_other.php in modules/ folder and sync
* Modify ggg.game.php to include it

require_once ('modules/ggg_other.php');

=== Creating a test class to run PHP locally ===

'''Ingredients:''' ggg.game.php, stubs
For this you need stubs of other method you can use this for example
https://github.com/elaskavaia/bga-sharedcode/raw/master/misc/module/table/table.game.php

Create another php files, i.e ggg_test.php
<pre>
<?php
define("APP_GAMEMODULE_PATH", "misc/"); // include path to stubs, which defines "table.game.php" and other classes
require_once ('eminentdomaine.game.php');

class MyGameTest1 extends MyGame { // this is your game class defined in ggg.game.php
function __construct() {
parent::__construct();
include '../material.inc.php';// this is how this normally included, from constructor
}

// override/stub methods here that access db and stuff
function getGameStateValue($var) {
if ($var == 'round')
return 3;
return 0;
}
}
$x = new MyGameTest1(); // instantiate your class
$p = $x->getGameProgression(); // call one of the methods to test
if ($p != 50)
echo "Test1: FAILED";
else
echo "Test1: PASSED";

</pre>

Run from command line like
php7 ggg_test.php

If you do it this way - you can also use local php debugger (i.e. integrated with IDE or command line).

=== Avoiding code in dojo declare style ===
Dojo class declarations are rather bizzare and do not work with most IDEs.
If you want to write in plain JS with classes, you can stub all the dojo define/declare stuff
and hook your class into that, so the classes are outside of this mess.

NOTE: this technique is for experienced developers, do not try it if you do not understand
the consequences.

This is complete example of game .js class
<pre>
// Testla is game name is has to be changed
class Testla {
constructor(game) {
console.log('game constructor');
this.game = game;
this.varfoo = new MyFoo(); // this example of class from custom module
}

setup(gamedatas) {
console.log("Starting game setup", this.varfoo);
this.gamedatas = gamedatas;
this.dojo.create("div", { class: 'whiteblock', innerHTML: _("hello") }, 'thething');
console.log("Ending game setup");
};
onEnteringState(stateName, args) {
console.log('onEnteringState : ' + stateName, args);
this.game.addActionButton('b1',_('Click Me'), (e)=>this.onButtonClick(e));
};
onLeavingState(stateName) {
console.log('onLeavingState : ' + stateName, args);
};
onUpdateActionButtons(stateName, args) {
console.log('onUpdateActionButtons : ' + stateName, args);
};
onButtonClick(event) {
console.log('onButtonClick',event);
};
};

define([
"dojo", "dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
g_gamethemeurl + '/modules/foo.js' // custom module if needed
],
function(dojo, declare) {
// testla is game name is has to be changed
return declare("bgagame.testla", ebg.core.gamegui, {
constructor: function() {
this.xapp = new Testla(this);
this.xapp.dojo = dojo;
},
setup: function(gamedatas) {
this.xapp.setup(gamedatas);
},
onEnteringState: function(stateName, args) {
this.xapp.onEnteringState(stateName, args?.args);
},
onLeavingState: function(stateName) {
this.xapp.onLeavingState(stateName, args);
},
onUpdateActionButtons: function(stateName, args) {
this.xapp.onUpdateActionButtons(stateName, args);
},
});
});

</pre>

=== More readable JS: onEnteringState ===

If you have a lot of states in onEnteringState or onUpdateActionButtons and friends - it becomes rather wild, you can do this trick to call some methods dynamically.

<pre>

onEnteringState: function(stateName, args) {
console.log('Entering state: ' + stateName, args);

// Call appropriate method
var methodName = "onEnteringState_" + stateName;
if (this[methodName] !== undefined) {
console.log('Calling ' + methodName, args.args);
this[methodName](args.args);
}
},

onEnteringState_playerTurn: function(args) { // this is args directly, not args.args
// process
},

onEnteringState_playerSomethingElse: function(args) {
// process
},

</pre>

Note: since its ignores the undefined functions you don't have define function for each state, but on the other hand you cannot make typos.
Same applies to onUpdateActionButtons except you pass 'args' to method, not args.args, and for onLeavingState where you don't pass anything.

=== Frameworks and Preprocessors ===

* [[BGA Type Safe Template]] - Setting up a fully typed project using typescript and more!
* [[Using Vue]] - work-in-progress guide on using the modern framework Vue.js to create a game
* [[Using Typescript and Scss]] - How to auto-build Typescript and SCSS files to make your code cleaner

== Backend ==

=== Assigning Player Order ===
Normally when game starts there is "natural" player order assigned randomly.

If you want to deliberatly assign player order at the start of the game (for example, in a game with teams options), you can do so by retrieving the initialization-only player attribute '''player_table_order''' and using it to assign values to '''player_no''' (which is normally assigned at the start of a game in the order in which players come to the table). (See [https://en.doc.boardgamearena.com/Game_database_model:_dbmodel.sql#The_player_table Game database model] for more details.)

'''Example:'''
<pre>
// Retrieve inital player order ([0=>playerId1, 1=>playerId2, ...])
$playerInitialOrder = [];
foreach ($players as $playerId => $player) {
$playerInitialOrder[$player['player_table_order']] = $playerId;
}
ksort($playerInitialOrder);
$playerInitialOrder = array_flip(array_values($playerInitialOrder));

// Player order based on 'playerTeams' option
$playerOrder = [0, 1, 2, 3];
switch ($this->getGameStateValue('playerTeams')) {
case $this->TEAM_1_2:
$playerOrder = [0, 2, 1, 3];
break;
case $this->TEAM_1_4:
$playerOrder = [0, 1, 3, 2];
break;
case $this->TEAM_RANDOM:
shuffle($playerOrder);
break;
default:
case $this->TEAM_1_3:
// Default order
break;
}

// Create players
// Note: if you added some extra field on "player" table in the database (dbmodel.sql), you can initialize it there.
$sql =
'INSERT INTO player (player_id, player_color, player_canal, player_name, player_avatar, player_no) VALUES ';
$values = [];

foreach ($players as $playerId => $player) {
$color = array_shift($default_colors);
$values[] =
"('" .
$playerId .
"','$color','" .
$player['player_canal'] .
"','" .
addslashes($player['player_name']) .
"','" .
addslashes($player['player_avatar']) .
"','" .
$playerOrder[$playerInitialOrder[$playerId]] .
"')";
}
$sql .= implode(',', $values);
$this->DbQuery($sql);
$this->reattributeColorsBasedOnPreferences(
$players,
$gameinfos['player_colors']
);
$this->reloadPlayersBasicInfos();
</pre>

=== Send different notifications to active player vs everybody else ===

'''Ingredients:''' ggg.js

Hack alert. This is a hack. We were hoping for proper solution by bga framework.

This will allow you to send notification with two message one for specific player and one for everybody else including spectators.
Note that this does not split the data - all data must be shared.

Add this to .js file (if you already overriding it merge obviously)
<pre>
/** @Override */
format_string_recursive: function(log, args) {
if (typeof args.log_others != 'undefined' && typeof args.player_id != 'undefined' && this.player_id != args.player_id)
log = args.log_others;
return this.inherited(arguments); // you must call this to call super
},
</pre>

Example of usage (from eminentdomain)
<pre>
$this->notifyAllPlayers('tokenMoved',
clienttranslate('${player_name} adds +2 Colonies to ${place_name}'), // notification with show for player with player_id
['player_id'=>$player_id, // this is mandatory
'log_others'=>clienttranslate('${player_name} adds +2 Colonies to an unknown planet'), // notification will show for others
...
]);
</pre>

=== Send transient notifications without incrementing move ID ===

'''Ingredients:''' ggg.php

Hack alert. This is a hack.

Use this if you need to send some transient notification that should not create a new move ID. The notification should be idempotent -- it should have no practical effect on the game state and would be '''safe to drop''' (e.g., it would not matter if a player never received this notification). For example, in a co-op game you want all players to see a real-time preview of some action, before the active player commits their turn.

Doing this mainly affects the instant replay & archive modes. During replay, the BGA framework automatically inserts a 1.5-second pause between each "move". With this hack, your transient notifications are not considered to be a "move", so no pause gets added.

; In ggg.php
<pre>
$this->not_a_move_notification = true; // note: do not increase the move counter
$this->notifyAllPlayers('cardsPreview', '', $args);
</pre>

Note: you cannot have code that send notification or even changes state after this, and you cannot reset this variable back either because it only takes effect when you exit action handling function

== Assorted Stuff ==

=== Out-of-turn actions: Un-pass ===

'''Ingredients:''' ggg.js, ggg.game.php, ggg.action.php, states.inc.php

In multiplayer game sometimes players passes but than they think more and want to un-Pass and redo their choice.
To re-active a player who passes some trickery required.

Define a special action that does that and hook it up.

In states.inc.php add an action to multipleactiveplayer state to "unpass", lets call it "actionCancel"

In ggg.action.php add action hook
public function actionCancel() {
$this->setAjaxMode();
$this->game->actionCancel();
$this->ajaxResponse();
}

In ggg.game.php add action handler
function actionCancel() {
$this->gamestate->checkPossibleAction('actionCancel');
$this->gamestate->setPlayersMultiactive(array ($this->getCurrentPlayerId() ), 'error', false);
}

Finally to call this in client ggg.js you would do something like:
<pre>
onUpdateActionButtons: function(stateName, args) {
if (this.isCurrentPlayerActive()) {
// ...
} else if (!this.isSpectator) { // player is NOT active but not spectator
switch (stateName) {
case 'playerTurnMultiPlayerState':
this.addActionButton('button_unpass', _('Oh no!'), 'onUnpass');
break;
}
}
}

onUnpass: function(e) {
this.bgaPerformAction("actionCancel", null, { checkAction: false }); // no checkAction!
}
</pre>
Although be careful that if the turn comes back to the player while he is about to click cancel, the action buttons will be updated and the player will misclick which can be quite frustrating. To avoid this, move the cancel button to another position, like to the left of pagemaintitletext:
dojo.place('button_unpass', 'pagemaintitletext', 'before');
Being out of the generalactions div, it won't be automatically destroyed like normal buttons, so you'll have to handle that yourself in onLeavingState. You might also want to change the button color to red (blue buttons for active player only, red buttons also for inactive players?)

Note: same technique can be used to do other out-of-turn actions, such as re-arranging cards in hand, exchanging resources, etc (i.e. if permitted by rules, such as "at any time player can...")

=== Multi Step Interactions: Select Worker/Place Worker - Using Selection ===

'''Ingredients:''' ggg.js

Simple way to implement something like that without extra states is to use "selection" mechanism. When user click on worker add some sort of class into that element i.e. 'selected' (which also have to have some indication by css i.e. outline).

Than user can click on placement zone, you can use dojo.query for "selected" element and use it along with zone id to send data to server. If proper worker is not selected yet can give a error message using this.showMessage(...) function.

Extra code required to properly cleanup selection between states.
Also when you do that sometimes you want to change the state prompt, see below 'Change state prompt'

=== Multi Step Interactions: Select Worker/Place Worker - Using Client States ===

'''Ingredients:''' ggg.js

I don't think its documented feature but there is a way to do client-only states, which is absolutely wonderful for few reasons
* When player interaction is two step process, such as select worker, place worker, or place worker, pick one of two resources of your choice
* When multi-step process can result of impossible situation and has to be undone (by rules)
* When multi-step process is triggered from multiple states (such as you can do same thing as activated card action, pass action or main action)

So lets do Select Worker/Place Worker

Define your server state as usual, i.e. playerMainTurn -> "You must pick up a worker".
Now define a client state, we only need "name" and "descriptionmyturn", lets say "client_playerPicksLocation". Always prefix names of client state with "client_" to avoid confusion. Now we have to do the following:
* Have a handler for onUpdateActionButtons for playerMainTurn to activate all possible workers he can pick
* When player clicks workers, remember the worker in one of the members of the main class, I usually use one called this.clientStateArgs.
* Transition to new client state
onWorker: function(e) {
var id = event.currentTarget.id;
dojo.stopEvent(event);
... // do validity checks
this.clientStateArgs.worker_id = id;
this.setClientState("client_playerPicksLocation", {
descriptionmyturn : _("${you} must select location"),
});
}
* Have a handler for onUpdateActionButtons for client_playerPicksLocation to activate all possible locations this worker can go AND add Cancel button (see below)
* Have a location handler which will eventually send a server request, using stored this.clientStateArgs.worker_id as worker id
* The cancel button should call a method to restore server state, also if you doing it for more than one state you can add this universally using this.on_client_state check

if (this.isCurrentPlayerActive()) {
if (this.on_client_state && !$('button_cancel')) {
this.addActionButton('button_cancel', _('Cancel'), dojo.hitch(this, function() {
this.restoreServerGameState();
}));
}
}
Note: usually I call my own function call this.cancelLocalStateEffects() which will do more stuff first then call restoreServerGameState(), same function is usually needs to be called when server request has failed (i.e. invalid move)

Note: If you need more than 2 steps, you may have to do client side animation to reflect the new state, which gets trickier because you have to undo that also on cancellation.

Code is available here [https://github.com/elaskavaia/bga-sharedcode/blob/master/sharedcode.js sharedcode.js] (its using playerTurnPlayCubes and client_selectCubeLocation).

=== Action Stack - Using Client States ===

Action stack required where game is very complex and use triggered effects that can "stack". It not always actual stack, it can be queue or random access.

Examples:
* Magic the Gathering - classic card game where effects go on Stack, that allows to counter spell and counter spell of counter spell (not on bga - it just example of mechanics)
* Ultimate Railroads - action taking game where effects can be executed in any order
* Lewis and Clark - card game where actions executed as queue

There is two ways of implementing it - on the server or the client.
For the server see article below.
The requirement for client side stack implementation is - all action can be undone, which means
* No dice rolls
* No card drawn
* No other players interaction

No snippets are here, as this will be too complex but basically flow is:
* You have a action/effect stack (queue/list) as js object attached to "this", i.e. this.unprocessed_actions
* When player plays a card, worker, etc, you read the effect of that card from the material file (client copy), and place into stack
* Then we call dispatch method which pulls the next action from the stack and change client state accordinly, i.e. this.setClientState("client_playerGainsCubes")
* When players acts on it - the action is removed from the stack and added to "server action arguments" list, this is another object which be used to send ajax call, i.e. this.clientStateArgs
* If nothing left in stack we can submit the ajax call assembling parameters from collected arguments (that can include action name)
* This method allows cheap undo - by restoring server state you will wipe out all user actions (but if you need intermediate aninmation you have to handle it yourself)

Code can be found in Ultimate Railroads game (but it is random access list - so it a bit complex) and Lewis and Clark (complexity - user can always deny part of any effect)

=== Action Stack - Using Server States ===

See definition of Action Stack above.

To implement you usually need another db table that has the following fields: index of effect - which is used for sorted access, type - which is essense of the effect (i.e. collect resource), some extra arguments (i.e. resource type and resource count), and usually owner of the effect (i.e. player id)
The flow is:
* There is some initial player state, where player can play card for example
* Player main action - pushes the card effect on stack, which also can cause triggered effects which also go on stack
* After action processing is finished switch to game state which is "dispatcher"
* Dispatcher pulls the top effect (whatever definition of the top is), changes the active player and changes the state to appropriate player state to collect response. The "top" can be choice of multiple actions, in this case player has to chose one before resolving the effect.
* Player state knows about the stack and pulls arguments (argX) from the effect arguments of the db
* Player action should clear up the top effect, and can possibly add more effects, then switch to "dispatcher" state again
* If stack is empty, dispatcher can either pick next player itself or use another game state which responsible for picking next player

Code can be found in Tapestry and Terraforming Mars.
=== Custom error/exception handling in JavaScript ===

; In ggg.php
Throw BgaUserException with some easy-to-identify prefix such as "!!!" and a custom error code. DO NOT TRANSLATE this message text. The exception will rollback database transaction and cancel all changes (including any notifications).
<pre>
function foo(bool $didConfirm = false): void
{
// do processing for the user's move
// afterwards, you determine this move will end the game
// so you want to rollback the transaction and require the user to confirm the move first

if ($gameIsEnding && !$didConfirm) {
throw new BgaUserException('!!!endGameConfirm', 9001);
}
}
</pre>

; In ggg.js
Override framework function showMessage to suppress the red banner message and gamelog message when you detect the "!!!" prefix
<pre>
/* @Override */
showMessage: function (msg, type) {
if (type == "error" && msg && msg.startsWith("!!!")) {
return; // suppress red banner and gamelog message
}
this.inherited(arguments);
},
</pre>

Deal with the error in your callback:
<pre>
fooAction: function (didConfirm) {
var data = {
foo: "bar",
didConfirm: !!didConfirm,
};
this.bgaPerformAction("fooAction", data).catch((error, errorMsg) => {
if (error && errorMsg == "!!!endGameConfirm") {
// your custom error handling goes here
// for example, show a confirmation dialog and repeat the action with additional param
this.confirmationDialog(
_("Doing the foo action now will end the game"),
() => this.fooAction(true)
);
}
});
},
</pre>

For custom global error handling, you could modify ajaxcallwrapper:
<pre>
ajaxcallwrapper: function (action, args, handler) {
if (!args) args = {};
args.lock = true;
args.version = this.gamedatas.version;
if (this.checkAction(action)) {
this.bgaPerformAction(
action,
args
).catch((error, errorMsg, errorCode) => {
if (error && errorMsg == "!!!checkVersion") {
this.infoDialog(
_("A new version of this game is now available"),
_("Reload Required"),
() => {
window.location.reload();
},
true
);
} else {
if (handler) handler(error, errorMsg, errorCode);
}
}
);
}
},
</pre>

=== Force players to refresh after new deploy ===

When you deploy a new version of your game, the PHP backend code is immediately updated but the JavaScript/HTML/CSS frontend code *does not update* for active players until they manually refresh the page (F5) in their browser. Obviously this is not ideal. In the best case, real-time tables don't see your shiny new enhancements. In the worst case, your old JS code isn't compatible with your new PHP code and the game breaks in strange ways (any bug reports filed will be false positives and unable to reproduce). To avoid any problems, you should force all players to immediately reload the page following a new deploy.

By throwing a "visible" exception (simplest solution), you'll get something like this which instructs the user to reload:

[[File:Force-refresh.png|950x950px]]

Or, if you combine this technique with the above custom error handling technique, you could do something a bit nicer. You could show a dialog box and automatically refresh the page when the user clicks "OK":

[[File:Reload-required.png|500x500px]]
; In ggg.php
Transmit the server version number in <code>getAllDatas()</code>.
<pre>
protected function getAllDatas(): array
{
$players = $this->getCollectionFromDb("SELECT player_id id, player_score score FROM player");
return [
'players' => $players,
'version' => intval($this->gamestate->table_globals[300]), // <-- ADD HERE
...
];
}
</pre>

Create a helper function to fail if the client and server versions mismatch. Note the version check uses <code>!=</code> instead of <code><</code> so it can support rollback to a previous deploy as well. ;-)
<pre>
public function checkVersion(int $clientVersion): void
{
if ($clientVersion != intval($this->gamestate->table_globals[300])) {
// Simplest way is to throw a "visible" exception
// It's ugly but comes with a "click here" link to refresh
throw new BgaVisibleSystemException($this->_("A new version of this game is now available. Please reload the page (F5)."));

// For something prettier, throw a "user" exception and handle in JS
// (see BGA cookbook section above on custom error handling)
throw new BgaUserException('!!!checkVersion');
}
}
</pre>
; In ggg.action.php
Create a helper function for actions:
<pre>
private function checkVersion()
{
$clientVersion = (int) $this->getArg('version', AT_int, false);
$this->game->checkVersion($clientVersion);
}
</pre>

Call <code>$this->checkVersion()</code> at the top of <b>every action function</b>, immediately after <code>$this->setAjaxMode()</code>:
<pre>
public function move()
{
$this->setAjaxMode();
$this->checkVersion(); // <-- ADD HERE
...
$this->ajaxResponse();
}
</pre>

; In ggg.js
Transmit the version (from gamedatas) as a parameter with every ajax call. For example, if you're already using a wrapper function for every ajax call, add it like this:
<pre>
ajaxcallwrapper: function (action, args) {
if (!args) args = {};
args.version = this.gamedatas.version; // <-- ADD HERE
this.bgaPerformAction(action, args);
},
</pre>

=== Disable / lock table creation for new deploy ===

If you are deploying a major new game version, especially if it involves upgrading production game databases, you may have a lot of angry players if you break their tables. Depending on your changes, you may be able to restore the previous version and fix the tables easily.

However, if a new deploy turns out bad and players created turn-based tables while it was live, it may be quite difficult to fix those tables, since they were created from a bad deploy.

The solution? You can announce in your game group that you are locking table creation, and then in your new version, add an impossible startcondition to an existing option.
Note: This only makes sense if you have a few games running in real time mode in the time of deployment, otherwise it won't achieve much, unless you wait at least a day for other turn based games to break (or not)

Here is an example of an option with only 2 values (if you don't have options at all you have to create a fake option to use this method, if you have more values - you have to list them all):

; In gameoptions.json
<pre>
"startcondition": {
"0": [ { "type": "minplayers", "value": 32, "message": "Maintenance in progress. Table creation is disabled." } ],
"1": [ { "type": "minplayers", "value": 32, "message": "Maintenance in progress. Table creation is disabled." } ]
},
</pre>
; In gameoptions.inc.php (older method if you have it in php)
<pre>
// TODO NEXT remove after testing deploy to upgrade, here 0 and 1 - replace with values of your option!
'startcondition' => [
0 => [ [ 'type' => 'minplayers', 'value' => 32, 'message' => totranslate('Maintenance in progress. Table creation is disabled.') ] ],
1 => [ [ 'type' => 'minplayers', 'value' => 32, 'message' => totranslate('Maintenance in progress. Table creation is disabled.') ] ],
],
</pre>

* Be sure to click "Reload game options configuration" after making this change, then test in studio (test that you cannot create any table)
* Deploy to production
* Now, when a player attempts to create a new table, they will see a red error bar with your "Maintenance in progress" message.
* Wait for screaming (if you have real times games in progress waiting 15 min probably ok, if you have only turn based games, probably a day)
* Once you confirm the new deploy looks good, you can revert the change in gameoptions.inc.php and do another deploy.

=== Local Storage ===

There is not much you can store in localStorage (https://developer.mozilla.org/docs/Web/API/Window/localStorage), since most stuff should be stored either in game db or in user prefrences,
but some stuff makes sense to store there, for example "zoom" level (if you use custom zooming). This setting really affect this specific host and specific browser, setting it localStorage makes most sense.

game.js
<pre>
setup: function (gamedatas) {
let zoom = localStorage.getItem(`${this.game_name}_zoom`);
this.setZoom(zoom);
...
},
</pre>
In this case setZoom is custom function to actually set it.
When zoom changed, for example when some buttons pressed, store current value (but sanitize it so it never so bad that game cannot be viewed

<pre>
setZoom: function (zoom) {
zoom = parseInt(zoom) || 0;
if (zoom === 0 || zoom < 0.1 || zoom > 10) {
zoom = 1;
}
this.zoom = zoom;
localStorage.setItem(`${this.game_name}_zoom`, "" + this.zoom);
... do actual zooming stuff
},
</pre>

=== Capture client JavaScript errors in the "unexpected error" log ===

PHP (backend) errors are recorded in the "unexpected error" log, but JavaScript (frontend) errors are only available in the browser itself. This means you have no visibility about things that go wrong in the client... unless you make clients report their errors to the server.

; In actions.php:
<pre>
public function jsError()
{
$this->setAjaxMode(false);
$this->game->jsError($_POST['userAgent'], $_POST['msg']);
$this->ajaxResponse();
}
</pre>

; In game.php:
<pre>
public function jsError($userAgent, $msg): void
{
$this->error("JavaScript error from User-Agent: $userAgent\n$msg // ");
}
</pre>

; In game.js:
<pre>
define(["dojo", "dojo/_base/declare", "ebg/core/gamegui", "ebg/counter"], function (dojo, declare) {
const uniqJsError = {};
...

return declare("bgagame.nowboarding", ebg.core.gamegui, {
...
/* @Override */
onScriptError(msg) {
if (!uniqJsError[msg]) {
uniqJsError[msg] = true;
console.error("⛔ Reporting JavaScript error", msg);
this.ajaxcall(
"/" + this.game_name + "/" + this.game_name + "/jsError.html",
{
msg,
userAgent: navigator.userAgent,
},
this,
() => {},
() => {},
"post"
);
}
this.inherited(arguments);
},
</pre>

== Algorithms ==

=== Generate permutations in lexicographic order ===

Use this when you have an array like [1, 2, 3, 4] and need to loop over some/all 24 permutations of possible ordering. This type of [https://www.php.net/manual/en/language.generators.syntax.php generator function] computes each possibility one at a time, making it vastly more efficient than either a normal iteration or recursive function that produce all possibilities up front.

<pre>
function generatePermutations(array $array): Generator
{
// https://en.wikipedia.org/wiki/Permutation#Generation_in_lexicographic_order
// Sort the array and this is the first permutation
sort($array);
yield $array;

$count = count($array);
do {
// Find the largest index k where a[k] < a[k + 1]
// End when no such index exists
$found = false;
for ($k = $count - 2; $k >= 0; $k--) {
$kvalue = $array[$k];
$knext = $array[$k + 1];
if ($kvalue < $knext) {
// Find the largest index l greater than k where a[k] < a[l]
for ($l = $count - 1; $l > $k; $l--) {
$lvalue = $array[$l];
if ($kvalue < $lvalue) {
// Swap a[k] and a[l]
[$array[$k], $array[$l]] = [$array[$l], $array[$k]];

// Reverse the sequence from a[k + 1] up to and including the final element
$reverse = array_reverse(array_slice($array, $k + 1));
array_splice($array, $k + 1, $count, $reverse);
yield $array;

// Restart with the new array to find the next permutation
$found = true;
break 2;
}
}
}
}
} while ($found);
}
</pre>

Usage:
<pre>
$cash = [4, 1, 2, 3, 4];
foreach ($this->generatePermutations($cash) as $p) {
// your code here to evaluate permutation $p
// first iteration: $p = [1, 2, 3, 4, 4]
// last (60th) iteration: $p = [4, 4, 3, 2, 1]
// break from loop once you achieve your goal
}
</pre>

[[Category:Studio]]

BGA Studio Cookbook

2024-09-24T14:37:28Z

Sguzzer Gunayer: /* Assorted Stuff */

This page is a cookbook of design and implementation recipes for BGA Studio framework.
For tooling and usage recipes see [[Tools and tips of BGA Studio]].
If you have your own recipes feel free to edit this page.

__TOC__

== Visual Effects, Layout and Animation ==

=== DOM manipulatons ===

==== Create pieces dynamically (using template) ====

'''Ingredients:''' ggg_ggg.tpl, ggg.js

Note: this method is recommended by BGA guildlines

Declared js template with variables in .tpl file, like this
<pre>
<script type="text/javascript">
// Javascript HTML templates
var jstpl_ipiece = '<div class="${type} ${type}_${color} inlineblock" aria-label="${name}" title="${name}"></div>';
</script>
</pre>

Use it like this in .js file
div = this.format_block('jstpl_ipiece', {
type : 'meeple',
color : 'ff0000',
name : 'Bob',
});

Then you do whatever you need to do with that div, this one specifically design to go to log entries, because it has embedded title (otherwise its a picture only) and no id.

Note: you could have place this variable in js itself, but keeping it in .tpl allows you to have your js code be free of HTML. Normally it never happens but
it is good to strive for it.
Note: you can also use string concatenation, its less readable. You can also use dojo dom object creation api's but its brutally verbose and its more unreadable.

==== Create pieces dynamically (using string concatenation) ====

'''Ingredients:''' ggg.js

<pre>
div = "<div class='meeple_"+color+"'></div>";
</pre>

or modern way

<pre>
div = `<div class='meeple_${color}'></div>`;
</pre>

==== Create all pieces statically ====

'''Ingredients:''' ggg_ggg.tpl, ggg.css, ggg.view.php (optional)

* Create ALL game pieces in html template (.tpl)
* ALL pieces should have unique id, and it should be meaningful, i.e. meeple_red_1
* Do not use inline styling
* Id of player's specific pieces should use some sort of 'color' identification, since player id cannot be used in static layout, you can use english color name, hex 6 char value, or color "number" (1,2,3...)
* Pieces should have separated class for its color, type, etc, so it can be easily styled in groups. In example below you now can style all meeples, all red meeples or all red tokens, or all "first" meeples

ggg.tpl:
<pre>
<div id="home_red" class="home_red home">
<div id="meeple_red_1" class="meeple red n1"></div>
<div id="meeple_red_2" class="meeple red n2"></div>
</div>
</pre>

ggg.css:

<pre>
.meeple {
width: 32px;
height: 39px;
background-image: url(img/78_64_stand_meeples.png);
background-size: 352px;
}

.meeple.red {
background-position: 30% 0%;
}
</pre>

* There should be straight forward mapping between server id and js id (or 1:1)
* You place objects in different zones of the layout, and setup css to take care of layout

<pre>
.home .meeple{
display: inline-block;
}
</pre>
* If you need to have a temporary object that look like original you can use dojo.clone (and change id to some temp id)
* If there is lots of repetition or zone grid you can use template generator, but inject style declaration in css instead of inline style for flexibility

Note:
* If you use this model you cannot use premade js components such as Stock and Zone
* You have to use alternative methods of animation (slightly altered) since default method will leave object with inline style attributes which you don't need

==== Use player color in template ====

'''Ingredients:''' ggg_ggg.tpl, ggg.view.php

.view.php:
<pre>
function build_page($viewArgs) {
// Get players & players number
$players = $this->game->loadPlayersBasicInfos();
$players_nbr = count($players);
/**
* ********* Place your code below: ***********
*/

// Set PCOLOR to the current player color hex
global $g_user;
$cplayer = $g_user->get_id();
if (array_key_exists($cplayer, $players)) { // may be not set if spectator
$player_color = $players [$cplayer] ['player_color'];
} else {
$player_color = 'ffffff'; // spectator
}
$this->tpl ['PCOLOR'] = $player_color;
</pre>

=== Status bar ===

==== Changing state prompt ====

State prompt is message displayed for player which usually comes from state description.
Sometimes you want to change it without changing state (one way is change state but locally, see client states above).

Simple way just change the html
<pre>
setMainTitle: function(text) {
$('pagemaintitletext').innerHTML = text;
},
// usage
onMeeple: function(event) {
//...
this.setMainTitle(_('You must select where meeple is going'));
},
</pre>

This however will not work with parameters and will not draw You in color, if you want this its more sophisticated:

<pre>
setDescriptionOnMyTurn : function(text) {
this.gamedatas.gamestate.descriptionmyturn = text;
var tpl = dojo.clone(this.gamedatas.gamestate.args);
if (tpl === null) {
tpl = {};
}
var title = "";
if (this.isCurrentPlayerActive() && text !== null) {
tpl.you = this.divYou();
}
title = this.format_string_recursive(text, tpl);

if (!title) {
this.setMainTitle(" ");
} else {
this.setMainTitle(title);
}
},
</pre>

Note: this method uses '''setMainTitle''' defined above and '''divYou''' defined in another section of this wiki.

=== Animation ===

==== Attach to new parent without destroying the object ====

BGA function attachToNewParent for some reason destroys the original, if you want similar function that does not you can use this
ggg.js

<pre>
/**
* This method will attach mobile to a new_parent without destroying, unlike original attachToNewParent which destroys mobile and
* all its connectors (onClick, etc)
*/
attachToNewParentNoDestroy: function (mobile_in, new_parent_in, relation, place_position) {

const mobile = $(mobile_in);
const new_parent = $(new_parent_in);

var src = dojo.position(mobile);
if (place_position)
mobile.style.position = place_position;
dojo.place(mobile, new_parent, relation);
mobile.offsetTop;//force re-flow
var tgt = dojo.position(mobile);
var box = dojo.marginBox(mobile);
var cbox = dojo.contentBox(mobile);
var left = box.l + src.x - tgt.x;
var top = box.t + src.y - tgt.y;

mobile.style.position = "absolute";
mobile.style.left = left + "px";
mobile.style.top = top + "px";
box.l += box.w - cbox.w;
box.t += box.h - cbox.h;
mobile.offsetTop;//force re-flow
return box;
},
</pre>

==== Animation on oversurface ====
If you use non-absolute position for your game elements (i.e you use layouts) - you cannot really use BGA animation functions. After years of fidding with different options I use
techique which I call animation on oversurface that works when parents use different zoom, rotation, etc

* You need another layer on top of everything - oversurface
* We create copy of the object on oversurface - to move
* We move the real object on final position - but make it invisible for now
* We move the phantom to final position applying required zoom and rotation (using css animation), then destroy it
* When animation is done we make original object visible in new position

The code is bit complex it can be found here

https://codepen.io/VictoriaLa/pen/gORvdJo

Game using it: century, ultimaterailroads

==== Scroll element into view ====
Ingredients: game.js

This function will scroll given node (div) into view and respect replays and archive mode

<pre>
scrollIntoViewAfter: function (node, delay) {
if (this.instantaneousMode || this.inSetup) {
return;
}
if (typeof g_replayFrom != "undefined") {
$(node).scrollIntoView();
return;
}
if (!delay) delay = 0;
setTimeout(() => {
$(node).scrollIntoView({ behavior: "smooth", block: "center" });
}, delay);
},
</pre>

=== Logs ===

==== Inject icon images in the log ====

Here is an example of what was done for Terra Mystica which is simple and straightforward:

<pre>
//Define the proper message
$message = clienttranslate('${player_name} gets ${power_income} via Structures');
if ($price > 0) {
$this->DbQuery("UPDATE player SET player_score = player_score - $price WHERE player_id = $player_id");
$message = clienttranslate('${player_name} pays ${vp_price} and gets ${power_income} via Structures');
}

// Notify
$this->notifyAllPlayers( "powerViaStructures", $message, array(
'i18n' => array( ),
'player_id' => $player_id,
'player_name' => $this->getUniqueValueFromDb( "SELECT player_name FROM player WHERE player_id = $player_id" ),
'power_tokens' => $power_tokens,
'vp_price' => $this->getLogsVPAmount($price),
'power_income' => $this->getLogsPowerAmount($power_income),
'newScore' => $this->getUniqueValueFromDb( "SELECT player_score FROM player WHERE player_id = $player_id" ),
'counters' => $this->getGameCounters(null),
) );
</pre>

With some functions to have the needed html added inside the substitution variable, such as:

<pre>
function getLogsPowerAmount( $amount ) {
return "<div class='tmlogs_icon' title='Power'><div class='power_amount'>$amount</div></div>";
}
</pre>
Note: injecting html from php is not ideal but easy, if you want more clean solution, use method below but it is a lot more sophisticated.

==== Inject images and styled html in the log ====

{{InfoBox|title=Warning — Translation|maxWidth=500|color=#c00|body='''In order to prevent interference with the translation process, keep in mind that you must only apply modifications to the args object, and not try to substitute the keys (the <code>${player_name}</code> parts of your string) in the log string.'''}}

So you want nice pictures in the game log. What do you do? The first idea that comes to mind is to send html from php in notifications (see method above).

This is a bad idea for many reasons:

* It's bad architecture. ui elements leak into the server, and now you have to manage the ui in multiple places.
* If you decided to change something in the ui in future version, replay logs for old games and tutorials may not work, since they use stored notifications.
* Log previews for old games become unreadable. (This is the log state before you enter the game replay, which is useful for troubleshooting and game analysis.)
* It's more data to transfer and store in the db.
* It's a nightmare for translators.

So what else can you do? You can use client side log injection to intercept log arguments (which come from the server) and replace them with html on the client side. Here are three different method you can use to achieve this.

===== Override <code>this.format_string_recursive()</code> method =====

'''Ingredients:''' ggg.js, ggg.game.php

I use this recipe for '''client side log injection''' to intercept log arguments (which come from the server) and replace them with html on the client side.

[[File:clientloginjection.png|left]]

ggg.js

<pre>

/** Override this function to inject html into log items. This is a built-in BGA method. */

/* @Override */
format_string_recursive : function format_string_recursive(log, args) {
try {
if (log && args && !args.processed) {
args.processed = true;

// list of special keys we want to replace with images
var keys = ['place_name','token_name'];

for ( var i in keys) {
var key = keys[i];
key in args && args[key] = this.getTokenDiv(key, args);

}
}
} catch (e) {
console.error(log,args,"Exception thrown", e.stack);
}
return this.inherited({callee: format_string_recursive}, arguments);
},
</pre>

'''Important:''' In the ''format_string_recursive'' method, the 'args' parameter will only contain arguments passed to it from the notify method in ggg.game.php (see below).

The 'log' parameter is the actual string that is inserted into the logs. You can perform additional js string manipulation on it.

<pre>
getTokenDiv : function(key, args) {
// ... implement whatever html you want here, example from sharedcode.js
var token_id = args[key];
var item_type = getPart(token_id,0);
var logid = "log" + (this.globalid++) + "_" + token_id;
switch (item_type) {
case 'wcube':
var tokenDiv = this.format_block('jstpl_resource_log', {
"id" : logid,
"type" : "wcube",
"color" : getPart(token_id,1),
});
return tokenDiv;

case 'meeple':
if ($(token_id)) {
var clone = dojo.clone($(token_id));

dojo.attr(clone, "id", logid);
this.stripPosition(clone);
dojo.addClass(clone, "logitem");
return clone.outerHTML;
}
break;

default:
break;
}

return "'" + this.clienttranslate_string(this.getTokenName(token_id)) + "'";
},
getTokenName : function(key) {
return this.gamedatas.token_types[key].name; // get name for the key, from static table for example
},
</pre>

Note that in this case the server simply injects token_id as a name, and the client substitutes it for the translated name or the picture.

ggg.game.php:

$this->notifyAllPlayers('playerLog',clienttranslate('Game moves ${token_name}'),['token_name'=>$token_id]);

'''Important:''' As noted above, only arguments actually passed by this method are available to the args parameter received in the client-side ''format_string_recursive'' method.

Sometimes it is the case that you want to pass arguments that are not actually included in the output message. For example, suppose we have a method like this:

$this->notifyAllPlayers('tokenPlaced',clienttranslate('Player placed ${token_name}'),array(
'token_name' => $token_id,
'zone_played' => $zone);

This will output "Player placed ${token_name}" in the log, and if we subscribe to a notification method activated by the "tokenPlaced" event in the client-side code, that method can make use of the 'zone_played' argument.

Now if you want to make some really cool things with game log, most probably you would need more arguments than are included in log message. The problem with that,
it will work at first, but if you reload game using F5 or when the game loads in turn based mode, you will loose your additional parameters, why? Because when game reloads it does not actually send same notifications, it sends special "hitstorical_log" notification where all parameters not listed in the message are removed. In example above, field zone_played would be removed from historical log as it is not included in message of the notification. You can till preserve specific arguments in historical log by adding special field preserve to notification arguments like this:

<pre>
$this->notifyAllPlayers('tokenPlaced',clienttranslate('Player placed ${token_name}'),array(
'token_name' => $token_id,
'zone_played' => $zone,
'preserve' => [ 'zone_played' ]
);
</pre>

Now you can use zone_played in format_string_recursive even in historical logs.

===== Use <code>:formatFunction</code> option provided by <code>dojo.string.substitute</code> =====

'''Ingredients:''' ggg.js, ggg.game.php, ggg_ggg.tpl, ggg.css

The above method will work in most of the cases, but if you use dotted keys such as <code>${card.name}</code> (which is supported by the framework, for private state args), the key won't be substituted because the <code>key in arg</code> test will fail. If so you need to rely either on this way, or the one after.

'''WARNING:''' using this method on an already advanced project will require you to go through all your notifications to change keys !

Under the hood, the '''this.format_string_recursive()''' function calls the '''dojo.string.substitute''' method which substitutes <code>${keys}</code> with the value provided. If you take a look at the [https://dojotoolkit.org/reference-guide/1.7/dojo/string.html#substitute documentation] and [https://github.com/dojo/dojo/blob/c3ceb017cfa25b703f5662dc83d1c8aae9bc5d81/string.js#L163 source code] you can notice that the key can be suffixed with a colon (<code>:</code>) followed by a function name. This will allow you to specify directly in the substitution string which keys need HTML injection.

First of all, you need to define your formatting function in the ggg.js file:
<pre>
[[ggg.js]]
getTokenDiv : function(value, key) {
//This is only an example implementation, you need to write your own.
//The method should return HTML code
switch (key) {
case 'html_injected_argument1':
return this.format_block('jstpl_HTMLLogElement1',{value: value});
case 'html_injected_argument2':
return this.format_block('jstpl_HTMLLogElement2',{value: value});
...
}
}
</pre>

Obviously you need to define the appropriate templates in the ggg_ggg.tpl file:
<pre>
[[ggg_ggg.tpl]]
let jstpl_HTMLLogElement1 = '<div class="log-element log-element-1-${value}"></div>';
let jstpl_HTMLLogElement2 = '<div class="log-element log-element-2-${value}"></div>';
...
</pre>
And the appropriate classes in ggg.css.

Then you need to add the <code>dojo/aspect</code> module at the top of the ggg.js file:

<nowiki>[[ggg.js]]</nowiki>
define([
"dojo", "dojo/_base/declare",
'''<span style="color:green;">"dojo/aspect",</span> //MUST BE IN THIRD POSITION''' (see [[#Including your own JavaScript module (II)|below]])
"ebg/core/gamegui",
"ebg/counter",
], function (dojo, declare, <span style="color:green;">'''aspect'''</span>) {
...

And you also need to add the following code in your <code>contructor</code> method in the ggg.js:

<nowiki>[[ggg.js]]</nowiki>
constructor: function(){

// ... skipped code ...
let gameObject = this; //Needed as the this object in aspect.before will not refer to the game object in which the formatting function resides
aspect.before(dojo.string, "substitute", function(template, map, transform) { //This allows you to modify the arguments of the dojo.string.substitute method before they're actually passed to it
return [template, map, transform, gameObject];
});

Now you're all set to inject HTML in your logs. To actually achieve this, you must specify the function name with the key like so:

<nowiki>[[ggg.game.php]]</nowiki>
$this->notifyAllPlayers("notificationName", clienttranslate("This log message contains ${plainTextArgument} and the following will receive HTML injection: ${html_injected_argument1:getTokenDiv}"), [
"plainTextArgument" => "some plain text here",
"html_injected_argument1" => "some value used by getTokenDiv",
]);

You're not limited writing only one function, you can write as many functions as you like, and have them each inject a specific type of HTML. You just need to specify the relevant function name after the column in the substitution key.

===== Use <code>transform</code> argument of <code>dojo.string.substitute</code> =====

'''Ingredients:''' ggg.js, ggg.game.php, ggg_ggg.tpl, ggg.css

This method is also relying on the use of <code>dojo.string.substitute</code> by the framework, and will use the <code>transform</code> argument, which, accordting to [https://github.com/dojo/dojo/blob/c3ceb017cfa25b703f5662dc83d1c8aae9bc5d81/string.js#L163 source code] and [https://dojotoolkit.org/reference-guide/1.7/dojo/string.html#substitute documentation] will be run on all the messages going through dojo.string.substitute.

'''WARNING:''' This method will be applied to all strings that go through dojo.string.substitute. As such you must take extra care not to substitute keys that may be used by the framework (i.e. ${id}). In order to do so, a good practise would be to prefix all keys that need substitution with a trigram of the game name.

Since all the keys will be fed to the tranform function, by default, it must return the value, substituted or not per your needs. You can define the function like this in the ggg.js file:

<nowiki>[[ggg.js]]</nowiki>
getTokenDiv : function(value, key) {
//This is only an example implementation, you need to write your own.
//The method should return HTML code
switch (key) {
case 'html_injected_argument1':
return this.format_block('jstpl_HTMLLogElement1',{value: value});
case 'html_injected_argument2':
return this.format_block('jstpl_HTMLLogElement2',{value: value});
...
default:
return value; //Needed otherwise regular strings won't appear since since the value isn't returned by the function
}
}

The templates must be defined in the ggg_ggg.tpl file and the corresponding CSS classes in the ggg.css file.

You need to add the following code at the beginning of the ggg.js file:

<nowiki>[[ggg.js]]</nowiki>
define([
"dojo", "dojo/_base/declare",
'''<span style="color:green;">"dojo/aspect",</span> //MUST BE IN THIRD POSITION''' (see [[#Including your own JavaScript module (II)|below]])
"ebg/core/gamegui",
"ebg/counter",
], function (dojo, declare, <span style="color:green;">'''aspect'''</span>) {
...

And the following code to the <code>constructor</code> method in ggg.js:

<nowiki>[[ggg.js]]</nowiki>
constructor: function(){
// ... skipped code ...
let transformFunction = dojo.hitch(this, "getTokenDiv"); //Needed as the this object in aspect.before will not refer to the game object in which the formatting function resides
aspect.before(dojo.string, "substitute", function(template, map, transform) {
if (undefined === transform) { //Check for a transform function presence, just in case
return [template, map, transformFunction];
}
});

Then you're all set for log injection, no need to change anything on the PHP side.

==== Processing logs on re-loading ====

You rarely need to process logs when reloading, but if you want to do something fancy you may have to do it after logs are loaded.
Logs are loaded asyncronously so you have to listen for logs to be fully loaded.
Unfortunately there is no direct way of doing it so this is the hack.

'''Hack alert''' - this extends undocumented function and may be broken when framework is updated

'''Ingredients:''' ggg.js

<pre>
/*
* [Undocumented] Override BGA framework functions to call onLoadingLogsComplete when loading is done
@Override
*/
setLoader: function(image_progress, logs_progress) {
this.inherited(arguments); // required, this is "super()" call, do not remove
//console.log("loader", image_progress, logs_progress)
if (!this.isLoadingLogsComplete && logs_progress >= 100) {
this.isLoadingLogsComplete = true; // this is to prevent from calling this more then once
this.onLoadingLogsComplete();
}
},

onLoadingLogsComplete: function() {
console.log('Loading logs complete');
// do something here
},
</pre>

=== Player Panel ===

==== Inserting non-player panel ====

'''Ingredients:''' ggg.js, ggg_ggg.tpl

If you want to insert non-player panel on the right side (for example to hold extra preferences, zooming controls, etc)

this can go pretty much anywhere in template it will be moved later

ggg_ggg.tpl:
<pre>
<div class='player_board_config' id="player_board_config">

<button id="zoom-out" class=" fa fa-search-minus fa-2x config-control"></button>
<button id="zoom-in" class=" fa fa-search-plus fa-2x config-control"></button>
<button id="show-settings" class="fa fa-cog fa-2x config-control "></button>
</div>
</pre>

some hackery required in js

ggg.js:
<pre>
/* @Override */
updatePlayerOrdering() {
this.inherited(arguments);
dojo.place('player_board_config', 'player_boards', 'first');
},
</pre>

=== Images and Icons ===

==== Accessing images from js ====

'''Ingredients:''' ggg.js

<pre>
// your game resources

var my_img = '<img src="'+g_gamethemeurl+'img/cards.jpg"/>';

// shared resources
var my_help_img = "<img class='imgtext' src='" + g_themeurl + "img/layout/help_click.png' alt='action' /> <span class='tooltiptext'>" +
text + "</span>";
</pre>

==== High-Definition Graphics ====

Some users will have screens which can display text and images at a greater resolution than the usual 72 dpi, e.g. the "Retina" screens on the 5k iMac, all iPads, and high-DPI screens on laptops from many manufacturers. If you can get art assets at this size, they will make your game look extra beautiful. You ''could'' just use large graphics and scale them down, but that would increase the download time and bandwidth for users who can't display them. Instead, a good way is to prepare a separate graphics file at exactly twice the size you would use otherwise, and add "@2x" at the end of the filename, e.g. if pieces.png is 240x320, then pieces@2x.png is 480x640.

There are two changes required in order to use the separate graphics files. First in your css, where you use a file, add a media query which overrides the original definition and uses the bigger version on devices which can display them. Ensuring that the "background-size" attribute is set means that the size of the displayed object doesn't change, but only is drawn at the improved dot pitch.
<pre>
.piece {
position: absolute;
background-image: url('img/pieces.png');
background-size:240px 320px;
z-index: 10;
}
@media (-webkit-min-device-pixel-ratio: 2), (min-device-pixel-ratio: 2), (min-resolution: 192dpi)
{
.piece {
background-image: url('img/pieces@2x.png');
}
}
</pre>

Secondly, in your setup function in javascript, you must ensure than only the appropriate one version of the file gets pre-loaded (otherwise you more than waste the bandwidth saved by maintaining the standard-resolution file). Note that the media query is the same in both cases:
<pre>
var isRetina = "(-webkit-min-device-pixel-ratio: 2), (min-device-pixel-ratio: 2), (min-resolution: 192dpi)";
if (window.matchMedia(isRetina).matches)
{
this.dontPreloadImage( 'pieces.png' );
this.dontPreloadImage( 'board.jpg' );
}
else
{
this.dontPreloadImage( 'pieces@2x.png' );
this.dontPreloadImage( 'board@2x.jpg' );
}
</pre>

==== Using CSS to create different colors of game pieces if you have only white piece ====

<pre>
background-color: #${color};
background-blend-mode: multiply;
background-image: url( 'img/mypiece.png');
mask: url('img/mypiece.png');
-webkit-mask: url('img/mypiece.png');
</pre>

where ${color} - is color you want

Note: piece has to be white (shades of gray). Sprite can be used too, just add add background-position as usual.

==== Accessing player avatar URLs ====

<pre>
getPlayerAvatar(playerId) {
let avatarURL = '';

if (null != $('avatar_' + playerId)) {
let smallAvatarURL = dojo.attr('avatar_' + playerId, 'src');
avatarURL = smallAvatarURL.replace('_32.', '_184.');
}
else {
avatarURL = 'https://x.boardgamearena.net/data/data/avatar/default_184.jpg';
}

return avatarURL;
},
</pre>

Note: This gets avatar URLs at 184x184 resolution. You can also use 92, 50, and 32 depending on which resolution you want.

==== Adding Image buttons ====

Its pretty trivial but just in case you need a working function:

ggg.js:
<pre>
addImageActionButton: function (id, div_html, handler) { // div_html is string not node
this.addActionButton(id, div_html, handler, '', false, 'gray');
dojo.style(id, "border", "none"); // remove ugly border
dojo.addClass(id, "bgaimagebutton"); // add css class to do more styling
return $(id); // return node for chaining
},

</pre>
Example of usage:
<pre>
this.addImageActionButton('button_coin',"<div class='coin'></div>", ()=>{ alert('Ha!'); });
</pre>

=== Other Fluff ===

==== Use thematic fonts ====

'''Ingredients:''' ggg.css

Sometime game elements use specific fonts of text, if you want to match it up you can load some specific font (IMPORTANT: from some '''free font''' source. See notes below).

[[File:Dragonline_font.png]]

.css
<pre>
/* latin-ext */
@font-face {
font-family: 'Qwigley';
font-style: normal;
font-weight: 400;
src: local('Qwigley'), local('Qwigley-Regular'), url(https://fonts.gstatic.com/s/qwigley/v6/2Dy1Unur1HJoklbsg4iPJ_Y6323mHUZFJMgTvxaG2iE.woff2) format('woff2');
unicode-range: U+0100-024F, U+1E00-1EFF, U+20A0-20AB, U+20AD-20CF, U+2C60-2C7F, U+A720-A7FF;
}
/* latin */
@font-face {
font-family: 'Qwigley';
font-style: normal;
font-weight: normal;
src: local('Qwigley'), local('Qwigley-Regular'), url(https://fonts.gstatic.com/s/qwigley/v6/gThgNuQB0o5ITpgpLi4Zpw.woff2) format('woff2');
unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02C6, U+02DA, U+02DC, U+2000-206F, U+2074, U+20AC, U+2212, U+2215, U+E0FF, U+EFFD, U+F000;
}
@font-face {
font-family: 'Qwigley';
font-style: normal;
font-weight: normal;
src: local('Qwigley'), local('Qwigley-Regular'), url(http://ff.static.1001fonts.net/q/w/qwigley.regular.ttf) format('ttf');
}

.zone_title {
display: inline-block;
position: absolute;
font: italic 32px/32px "Qwigley", cursive;
height: 32px;
width: auto;
}
</pre>

'''NB:''' if you need to include a font that's not available online, an extra action will be needed from an admin. Please include the font file(s) in your img directory, and mention it to admins when requesting your game to be moved to alpha. '''Please remember that the font has to be free, and include a .txt with all appropriate license information about the font.'''
You can look for free fonts (for example) on https://fonts.google.com or https://www.fontsquirrel.com/)

'''Content Security Policy'''

BGA runs a Content Security Policy which will limit the origins from which you can load external fonts, in order to prevent license abuse.

The CSP is a whitelist of allowed origins. To see the list, view the response headers of any page on Studio, and look for the "Content-Security-Policy" header.

You will specifically want to check for the font-src token within these headers, and limit any external fonts to these sources.

'''This list is subject to change''' but as of the time of writing, the only acceptabled external sites are use.typekit.net and fonts.gstatic.com.

=== Scale to fit for big boards ===

'''Ingredients:''' ggg_ggg.tpl, ggg.js

Lets say you have huge game board, and lets say you want it to be 1400px wide. Besides the board there will be side bar which is 240 and trim.
My display is 1920 wide so it fits, but there is big chance other people won't have that width. What do you do?

You have to decide:
* If board does not fit you want scale whole thing down, the best way is probably use viewport (see https://en.doc.boardgamearena.com/Your_game_mobile_version)
* You can leave the board as is and make sure it is scrollable horizonatally
* You add custom scale just for the board (can add user controls - and hook to transform: scale())

I tried to auto-scale but this just does work, too many variables - browser zoom, 3d mode, viewport, custom bga scaling, devicePixelRatio - all create some impossible coctail of zooming...
Here is scaling functing for custom user scaling

ggg_ggg.tpl:
<pre>
<div id="thething" class="thething">
... everything else you declare ...
</div>
</pre>

ggg.js:
<pre>
onZoomPlus: function() {
this.setZoom(this.zoom + 0.1);
},
onZoomMinus: function() {
this.setZoom(this.zoom - 0.1);
},

setZoom: function (zoom) {
zoom = parseInt(zoom) || 0;
if (zoom === 0 || zoom < 0.1 || zoom > 10) {
zoom = 1;
}
this.zoom = zoom;
var inner = document.getElementById("thething");

if (zoom == 1) {
inner.style.removeProperty("transform");
inner.style.removeProperty("width");
} else {
inner.style.transform = "scale(" + zoom + ")";
inner.style.transformOrigin = "0 0";
inner.style.width = 100 / zoom + "%";
}
localStorage.setItem(`${this.game_name}_zoom`, "" + this.zoom);
this.onScreenWidthChange();
},
</pre>

=== Dynamic tooltips ===

If you really need a dynamic tooltip you can use this technique. (Only use it if the static tooltips provided by the BGA framework are not sufficient.)

new dijit.Tooltip({
connectId: ["divItemId"],
getContent: function(matchedNode){
return "... calculated ...";
}
});

This is an out-of-the-box djit.Tooltip. It has a ''getContent'' method which is called dynamically.

The string returned by getContent() becomes the innerHTML of the tooltip, so it can be anything. In this example matchedNode is a dojo node representing dom object with id of "divItemId" but there are more parameters which I am not posting here which allows more sophisticated subnode queries (i.e. you can attach tooltip to all nodes with class or whatever).

[https://dojotoolkit.org/reference-guide/1.10/dijit/Tooltip.html dijit.Tooltip]

It's not part of the BGA API so use at your own risk.

=== Rendering text with players color and proper background ===

'''Ingredients:''' ggg.js

<pre>
/* Implementation of proper colored You with background in case of white or light colors */

divYou: function() {
var color = this.gamedatas.players[this.player_id].color;
var color_bg = "";
if (this.gamedatas.players[this.player_id] && this.gamedatas.players[this.player_id].color_back) {
color_bg = "background-color:#" + this.gamedatas.players[this.player_id].color_back + ";";
}
var you = "<span style=\"font-weight:bold;color:#" + color + ";" + color_bg + "\">" + __("lang_mainsite", "You") + "</span>";
return you;
},

/* Implementation of proper colored player name with background in case of white or light colors */

divColoredPlayer: function(player_id) {
var color = this.gamedatas.players[player_id].color;
var color_bg = "";
if (this.gamedatas.players[player_id] && this.gamedatas.players[player_id].color_back) {
color_bg = "background-color:#" + this.gamedatas.players[player_id].color_back + ";";
}
var div = "<span style=\"color:#" + color + ";" + color_bg + "\">" + this.gamedatas.players[player_id].name + "</span>";
return div;
},
</pre>

=== Cool realistic shadow effect with CSS ===

==== Rectangles and circles ====

It is often nice to have a drop shadow around tiles and tokens, to separate them from the table visually. It is very easy to add a shadow to rectangular elements, just add this to your css:

<pre>
.xxx-tile {
box-shadow: 3px 3px 3px #000000a0;
}
</pre>

box-shadow obeys '''border-radius''' of the element, so it will look good for rounded rectangles, and hence also circles (if border-radius is set appropriately).

box-shadow also supports various other parameters and can be used to achieve effects such as glowing, borders, inner shadows etc. If you need to animate a box-shadow, you may be able to get better performance (avoiding redraws) if you attach the shadow to another element (possibly an ::after pseudo-element) and change only the '''opacity''' of that element.

==== Irregular Shapes ====

If you wish to make a shadow effect for game pieces that are not a rectangle, but your game pieces are drawn from rectangles in a PNG image, you can apply the shadow to the piece using any art package and save it inside the image. This usually will yield the best performance. Remember to account for the size of the shadow when you lay out images in the sprite sheet.

However that sometimes will not be an option, for example if the image needs to be rotated while the shadow remains offset in the same direction. In this case, one option is to not use box-shadow but use filter, which is supported by recent major browsers. This way, you can use the alpha channel of your element to drop a shadow. This even work for transparent backgrounds, so that if you are using the "CSS-sprite" method, it will work!

For instance:

<pre>
.xxx-token {
filter: drop-shadow(0px 0px 1px #000000);
}
</pre>

Beware that some browsers still do not always draw drop-shadow correctly. In particular, Safari frequently leaves bits of shadow behind when objects move around the screen. In Chrome, shadows sometimes flicker badly if another element is animating close by. Some of these correctness issues can be solved by adding '''isolation: isolate; will-change: filter;''' to affected elements, but this significantly affects redraw performance.

Beware of performance issues - particularly on Safari (MacOS, iPhone and iPad). Keep in mind that drop-shadow are very GPU intensive. This becomes noticeable once you have about 40 components with drop-shadow filter. If that is your case, you can quite easily implement a user preference to disable shadows for users on slower machines:

gameoptions.inc.php
<pre>
100 => array(
'name' => totranslate('Shadows'),
'needReload' => true, // after user changes this preference game interface would auto-reload
'values' => array(
1 => array( 'name' => totranslate( 'Enabled' ), 'cssPref' => '' ),
2 => array( 'name' => totranslate( 'Disabled' ), 'cssPref' => 'no-shadow' )
)
),
</pre>

[game].css
<pre>
.no-shadow * {
filter: none !important;
}
</pre>For Safari, it is usually better to simply disable drop-shadow completely: [[Game interface stylesheet: yourgamename.css#Warning: using drop-shadow]].

==== Shadows with clip-path ====

For some reason, a shadow will not work together with clip-path on one element. To use both clip-path (when for example using .svg to cut out cardboard components from your .jpg spritesheet) and drop-shadow, you need to wrap the element into another one, and apply drop-shadow to the outer one, and clip-path to the inner one.

<pre>
<div class='my-token-wrap'>
<div class='my-token'>
</div>
</div>
</pre>
<pre>
.my-token-wrap {
filter: drop-shadow(0px 0px 1px #000000);
}
.my-token-wrap .my-token {
clip-path: url(#my-token-path);
}
</pre>

=== Using the CSS classes from the state machine ===

If you need to hide or show stuff depending on the state of your game, you can of course use javascript, but CSS is hand enough for that. The #overall-content element does change class depending on the game state. For instance, if you are in state ''playerTurn'', it will have the class ''gamestate_playerTurn''.

So now, if you want to show the discard pile only during player turns, you may use:

<pre>
#discard_pile { display: none }
.gamestate_playerTurn #discard_pile { display: block }
</pre>

This can be used if you want to change sizing of elements, position, layout or visual appearance.

== Game Model and Database design ==

=== Database for The euro game ===
Lets say we have a game with workers, dice, tokens, board, resources, money and vp. Workers and dice can be placed in various zones on the board, and you can get resources, money, tokens and vp in your home zone. Also tokens can be flipped or not flipped.

[[File:Madeira board.png]]

Now lets try to map it, we have
* (meeple,zone)
* (die, zone, sideup)
* (resource cube/money token/vp token,player home zone)
* (token, player home zone, flip state)
We can notice that resource and money are uncountable, and don't need to be track individually so we can replace our mapping to
* (resource type/money,player home zone, count)
And vp stored already for us in player table, so we can remove it from that list.

Now when we get to encode it we can see that everything can be encoded as (object,zone,state) form, where object and zone is string and state is integer. The resource mapping is slightly different semantically so you can go with two table, or counting using same table with state been used as count for resources.

So the piece mapping for non-grid based games can be in most case represented by (string: token_key, string: token_location, int: token_state), example of such database schema can be found here: [https://github.com/elaskavaia/bga-sharedcode/blob/master/dbmodel.sql dbmodel.sql] and class implementing access to it here [https://github.com/elaskavaia/bga-sharedcode/blob/master/modules/tokens.php table.game.php].

Variant 1: Minimalistic

CREATE TABLE IF NOT EXISTS `token` (
`token_key` varchar(32) NOT NULL,
`token_location` varchar(32) NOT NULL,
`token_state` int(10),
PRIMARY KEY (`token_key`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

{| class="wikitable"
|+token
! token_key
! token_location
! token_state
|-
|meeple_red_1
|home_red
|0
|-
|dice_black_2
|board_guard
|1
|-
|dice_green_1
|board_action_mayor
|3
|-
|bread
|home_red
|5
|}

Now how we represent resource counters such as bread?
Using same table from we simply add special counter token for bread and use state to indicate the count. Note to keep first column unique we have to add player identification for that counter, i.e. ff0000 is red player.

{| class="wikitable"
|+token
! token_key
! token_location
! token_state
|-
|bread_ff0000
|tableau_ff0000
|5
|}

See php module for this table here https://github.com/elaskavaia/bga-sharedcode/blob/master/modules/tokens.php

Variant 2: Additional resource table, resource count for each player id

CREATE TABLE IF NOT EXISTS `resource` (
`player_id` int(10) unsigned NOT NULL,
`resource_key` varchar(32) NOT NULL,
`resource_count` int(10) signed NOT NULL,
PRIMARY KEY (`player_id`,`resource_key`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

ALTER TABLE resource ADD CONSTRAINT fk_player_id FOREIGN KEY (player_id) REFERENCES player(player_id);

{| class="wikitable"
|+resource
! player_id
! resource_key
! resource_count
|-
|123456
|bread
|5
|}

Variant 3: More normalised

This version is similar to "card" table from hearts tutorial, you can also use exact cards database schema and Deck implementation for most purposes (even you not dealing with cards).

CREATE TABLE IF NOT EXISTS `token` (
`token_id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`token_type` varchar(16) NOT NULL,
`token_arg` int(11) NOT NULL,
`token_location` varchar(32) NOT NULL,
`token_state` int(10),
PRIMARY KEY (`token_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

{| class="wikitable"
|+token
! token_id
! token_type
! token_arg
! token_location
! token_state
|-
|22
|meeple
|123456
|home_123456
|0
|-
|23
|dice
|2
|board_guard
|1
|-
|26
|dice
|1
|board_action_mayor
|3
|-
|49
|bread
|0
|home_123456
|5
|}

Advantages of this would be is a bit more straightforward to do some queries in db, disadvantage its hard to read (as you can compare with previous example, you
cannot just look at say, ah I know what it means). Another questionable advantage is it allows you to do id randomisation, so it hard to do crafted queries to
cheat, the down side of that you cannot understand it either, and handcraft db states for debugging or testing.

=== Database for The card game ===

Lets say you have a standard card game, player have hidden cards in hand, you can draw card from draw deck, play card on tableau and discard to discard pile.
We have to design database for such game.

In real word to "save" the game we take a picture a play area, save cards from it, then put away draw deck, discard and hand of each player separately and mark it, also we will record current scoring (if any) and who's turn was it.

* Framework handles state machine transition, so you don't have to worry about database design for that (i.e. who's turn it is, what phase of the game we are at, you still have to design it but part of state machine step)
* Also framework supports basic player information, color, order around the table, basic scoring, etc, so you don't have to worry about it either
* The only thing you need in our database is state of the "board", which is "where each pieces is, and in what state", or (position,rotation) pair.

Lets see what we have for that:
* The card state is very simple, its usually "face up/face down", "tapped/untapped", "right side up/up side down"
* As position go we never need real coordinates x,y,z. We need to know what "zone" card was, and depending on the zone it may sometimes need an extra "z" or "x" as card order. The zone position usually static or irrelevant.
* So our model is: we have cards, which have some attributes, at any given point in time they belong to a "zone", and can also have order and state
* Now for mapping we should consider what information changes and what information is static, later is always candidate for material file
* For dynamic information we should try to reduce amount of fields we need
** we need at least a field for card, so its one
** we need to know what zone cards belong to, its 2
** and we have possibly few other fields, if you look closely at you game you may find out that most of the zone only need one attribute at a time, i.e. draw pile always have cards face down, hand always face up, also for hand and discard order does not matter at all (but for draw it does matter). So in majority of cases we can get away with one single extra integer field representing state or order
* In real database both card and zone will be integers as primary keys referring to additional tables, but in our case its total overkill, so they can be strings as easily

Variant 1: Minimalistic

<pre>
CREATE TABLE IF NOT EXISTS `card` (
`card_key` varchar(32) unsigned NOT NULL,
`card_location` varchar(32) NOT NULL,
`card_state` int(11) NOT NULL,
PRIMARY KEY (`card_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

Variant 2: More normalised

This version supported by Deck php class, so unless you want to rewrite db access layer go with this one

<pre>
CREATE TABLE IF NOT EXISTS `card` (
`card_id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`card_type` varchar(16) NOT NULL,
`card_type_arg` int(11) NOT NULL,
`card_location` varchar(16) NOT NULL,
`card_location_arg` int(11) NOT NULL,
PRIMARY KEY (`card_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

Note: if you using this schema, some zones/locations have special semantic. The 'hand' location is actually multiple locations - one per player, but player id is encoded as card_location_arg. If 'hand' in your game is ordered, visible or can have some other card states, you cannot use hand location (replacement is hand_<player_id> or hand_<color_id>)

== Code Organization ==

=== Including your own JavaScript module ===
'''Ingredients:''' ggg.js, modules/ggg_other.js

* Create ggg_other.js in modules/ folder and sync
<pre>
define([
"dojo", "dojo/_base/declare"
], function( dojo, declare )
{
return declare("bgagame.other", null, { // null here if we don't want to inherit from anything
constructor: function(){},
mystuff: function(){},
});

});

</pre>
* Modify ggg.js to include it

define([ "dojo", "dojo/_base/declare", "ebg/core/gamegui", "ebg/counter",
g_gamethemeurl + "modules/ggg_other.js" // load my own module!!!
], function(dojo,
declare) {

use it

foo = new bgagame.other();

=== Including your own JavaScript module (II) ===

* Create ggg_other.js in modules/ folder and sync

define([], function () {
return "value";
});

* Modify ggg.js to include it

define([
"dojo",
"dojo/_base/declare",
"bgagame/modules/ggg_other",
"ebg/core/gamegui",
"ebg/counter"
], function(dojo, declare, other) {

});

This is maybe a little bit more the idea of the AMD Loader than the first option, although the first option should work as well.

A little explanation to this:
The define function loads all the modules listed in the array and calls the following function with these loaded modules as parameters.
By putting your module at the third position in the array it is passed as the third parameter to the function. Be aware that the modules are resolved by position only, not by name. So you can load the module '''ggg_other''' and pass it as a parameter with the name '''other'''. '''gamegui''' and '''counter''' are passed in as well, but when the parameters are not defined they are just skipped. Because these modules put their content into the global scope it does not matter and you can use them from there.

In the example above the string "value" is passed for the parameter '''other''', but the function in your module can return whatever you want. It can be an object, an array, something you declared with dojo.declare, you can return even functions.
Your module can load other modules. Just put them in the array at the beginning and pass them as parameters to your function.
The advantage of passing the values as parameter is that you do not need to put these values in the global scope, so they can't be collisions with values defined in other scripts or the BGA Framework.

The dojo toolkit provides good documentation to all of its components, the complete documentation for the AMD-Loader is here:
https://dojotoolkit.org/documentation/tutorials/1.10/modules/index.html It should be still correct, even as it seems to be only for version 1.10

=== Including your own PHP module ===
'''Ingredients:''' ggg.game.php, modules/ggg_other.php

* Create ggg_other.php in modules/ folder and sync
* Modify ggg.game.php to include it

require_once ('modules/ggg_other.php');

=== Creating a test class to run PHP locally ===

'''Ingredients:''' ggg.game.php, stubs
For this you need stubs of other method you can use this for example
https://github.com/elaskavaia/bga-sharedcode/raw/master/misc/module/table/table.game.php

Create another php files, i.e ggg_test.php
<pre>
<?php
define("APP_GAMEMODULE_PATH", "misc/"); // include path to stubs, which defines "table.game.php" and other classes
require_once ('eminentdomaine.game.php');

class MyGameTest1 extends MyGame { // this is your game class defined in ggg.game.php
function __construct() {
parent::__construct();
include '../material.inc.php';// this is how this normally included, from constructor
}

// override/stub methods here that access db and stuff
function getGameStateValue($var) {
if ($var == 'round')
return 3;
return 0;
}
}
$x = new MyGameTest1(); // instantiate your class
$p = $x->getGameProgression(); // call one of the methods to test
if ($p != 50)
echo "Test1: FAILED";
else
echo "Test1: PASSED";

</pre>

Run from command line like
php7 ggg_test.php

If you do it this way - you can also use local php debugger (i.e. integrated with IDE or command line).

=== Avoiding code in dojo declare style ===
Dojo class declarations are rather bizzare and do not work with most IDEs.
If you want to write in plain JS with classes, you can stub all the dojo define/declare stuff
and hook your class into that, so the classes are outside of this mess.

NOTE: this technique is for experienced developers, do not try it if you do not understand
the consequences.

This is complete example of game .js class
<pre>
// Testla is game name is has to be changed
class Testla {
constructor(game) {
console.log('game constructor');
this.game = game;
this.varfoo = new MyFoo(); // this example of class from custom module
}

setup(gamedatas) {
console.log("Starting game setup", this.varfoo);
this.gamedatas = gamedatas;
this.dojo.create("div", { class: 'whiteblock', innerHTML: _("hello") }, 'thething');
console.log("Ending game setup");
};
onEnteringState(stateName, args) {
console.log('onEnteringState : ' + stateName, args);
this.game.addActionButton('b1',_('Click Me'), (e)=>this.onButtonClick(e));
};
onLeavingState(stateName) {
console.log('onLeavingState : ' + stateName, args);
};
onUpdateActionButtons(stateName, args) {
console.log('onUpdateActionButtons : ' + stateName, args);
};
onButtonClick(event) {
console.log('onButtonClick',event);
};
};

define([
"dojo", "dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
g_gamethemeurl + '/modules/foo.js' // custom module if needed
],
function(dojo, declare) {
// testla is game name is has to be changed
return declare("bgagame.testla", ebg.core.gamegui, {
constructor: function() {
this.xapp = new Testla(this);
this.xapp.dojo = dojo;
},
setup: function(gamedatas) {
this.xapp.setup(gamedatas);
},
onEnteringState: function(stateName, args) {
this.xapp.onEnteringState(stateName, args?.args);
},
onLeavingState: function(stateName) {
this.xapp.onLeavingState(stateName, args);
},
onUpdateActionButtons: function(stateName, args) {
this.xapp.onUpdateActionButtons(stateName, args);
},
});
});

</pre>

=== More readable JS: onEnteringState ===

If you have a lot of states in onEnteringState or onUpdateActionButtons and friends - it becomes rather wild, you can do this trick to call some methods dynamically.

<pre>

onEnteringState: function(stateName, args) {
console.log('Entering state: ' + stateName, args);

// Call appropriate method
var methodName = "onEnteringState_" + stateName;
if (this[methodName] !== undefined) {
console.log('Calling ' + methodName, args.args);
this[methodName](args.args);
}
},

onEnteringState_playerTurn: function(args) { // this is args directly, not args.args
// process
},

onEnteringState_playerSomethingElse: function(args) {
// process
},

</pre>

Note: since its ignores the undefined functions you don't have define function for each state, but on the other hand you cannot make typos.
Same applies to onUpdateActionButtons except you pass 'args' to method, not args.args, and for onLeavingState where you don't pass anything.

=== Frameworks and Preprocessors ===

* [[BGA Type Safe Template]] - Setting up a fully typed project using typescript and more!
* [[Using Vue]] - work-in-progress guide on using the modern framework Vue.js to create a game
* [[Using Typescript and Scss]] - How to auto-build Typescript and SCSS files to make your code cleaner

== Backend ==

=== Assigning Player Order ===
Normally when game starts there is "natural" player order assigned randomly.

If you want to deliberatly assign player order at the start of the game (for example, in a game with teams options), you can do so by retrieving the initialization-only player attribute '''player_table_order''' and using it to assign values to '''player_no''' (which is normally assigned at the start of a game in the order in which players come to the table). (See [https://en.doc.boardgamearena.com/Game_database_model:_dbmodel.sql#The_player_table Game database model] for more details.)

'''Example:'''
<pre>
// Retrieve inital player order ([0=>playerId1, 1=>playerId2, ...])
$playerInitialOrder = [];
foreach ($players as $playerId => $player) {
$playerInitialOrder[$player['player_table_order']] = $playerId;
}
ksort($playerInitialOrder);
$playerInitialOrder = array_flip(array_values($playerInitialOrder));

// Player order based on 'playerTeams' option
$playerOrder = [0, 1, 2, 3];
switch ($this->getGameStateValue('playerTeams')) {
case $this->TEAM_1_2:
$playerOrder = [0, 2, 1, 3];
break;
case $this->TEAM_1_4:
$playerOrder = [0, 1, 3, 2];
break;
case $this->TEAM_RANDOM:
shuffle($playerOrder);
break;
default:
case $this->TEAM_1_3:
// Default order
break;
}

// Create players
// Note: if you added some extra field on "player" table in the database (dbmodel.sql), you can initialize it there.
$sql =
'INSERT INTO player (player_id, player_color, player_canal, player_name, player_avatar, player_no) VALUES ';
$values = [];

foreach ($players as $playerId => $player) {
$color = array_shift($default_colors);
$values[] =
"('" .
$playerId .
"','$color','" .
$player['player_canal'] .
"','" .
addslashes($player['player_name']) .
"','" .
addslashes($player['player_avatar']) .
"','" .
$playerOrder[$playerInitialOrder[$playerId]] .
"')";
}
$sql .= implode(',', $values);
$this->DbQuery($sql);
$this->reattributeColorsBasedOnPreferences(
$players,
$gameinfos['player_colors']
);
$this->reloadPlayersBasicInfos();
</pre>

=== Send different notifications to active player vs everybody else ===

'''Ingredients:''' ggg.js

Hack alert. This is a hack. We were hoping for proper solution by bga framework.

This will allow you to send notification with two message one for specific player and one for everybody else including spectators.
Note that this does not split the data - all data must be shared.

Add this to .js file (if you already overriding it merge obviously)
<pre>
/** @Override */
format_string_recursive: function(log, args) {
if (typeof args.log_others != 'undefined' && typeof args.player_id != 'undefined' && this.player_id != args.player_id)
log = args.log_others;
return this.inherited(arguments); // you must call this to call super
},
</pre>

Example of usage (from eminentdomain)
<pre>
$this->notifyAllPlayers('tokenMoved',
clienttranslate('${player_name} adds +2 Colonies to ${place_name}'), // notification with show for player with player_id
['player_id'=>$player_id, // this is mandatory
'log_others'=>clienttranslate('${player_name} adds +2 Colonies to an unknown planet'), // notification will show for others
...
]);
</pre>

=== Send transient notifications without incrementing move ID ===

'''Ingredients:''' ggg.php

Hack alert. This is a hack.

Use this if you need to send some transient notification that should not create a new move ID. The notification should be idempotent -- it should have no practical effect on the game state and would be '''safe to drop''' (e.g., it would not matter if a player never received this notification). For example, in a co-op game you want all players to see a real-time preview of some action, before the active player commits their turn.

Doing this mainly affects the instant replay & archive modes. During replay, the BGA framework automatically inserts a 1.5-second pause between each "move". With this hack, your transient notifications are not considered to be a "move", so no pause gets added.

; In ggg.php
<pre>
$this->not_a_move_notification = true; // note: do not increase the move counter
$this->notifyAllPlayers('cardsPreview', '', $args);
</pre>

Note: you cannot have code that send notification or even changes state after this, and you cannot reset this variable back either because it only takes effect when you exit action handling function

== Assorted Stuff ==

=== Out-of-turn actions: Un-pass ===

'''Ingredients:''' ggg.js, ggg.game.php, ggg.action.php, states.inc.php

In multiplayer game sometimes players passes but than they think more and want to un-Pass and redo their choice.
To re-active a player who passes some trickery required.

Define a special action that does that and hook it up.

In states.inc.php add an action to multipleactiveplayer state to "unpass", lets call it "actionCancel"

In ggg.action.php add action hook
public function actionCancel() {
$this->setAjaxMode();
$this->game->actionCancel();
$this->ajaxResponse();
}

In ggg.game.php add action handler
function actionCancel() {
$this->gamestate->checkPossibleAction('actionCancel');
$this->gamestate->setPlayersMultiactive(array ($this->getCurrentPlayerId() ), 'error', false);
}

Finally to call this in client ggg.js you would do something like:
<pre>
onUpdateActionButtons: function(stateName, args) {
if (this.isCurrentPlayerActive()) {
// ...
} else if (!this.isSpectator) { // player is NOT active but not spectator
switch (stateName) {
case 'playerTurnMultiPlayerState':
this.addActionButton('button_unpass', _('Oh no!'), 'onUnpass');
break;
}
}
}

onUnpass: function(e) {
this.bgaPerformAction("actionCancel", null, { checkAction: false }); // no checkAction!
}
</pre>
Although be careful that if the turn comes back to the player while he is about to click cancel, the action buttons will be updated and the player will misclick which can be quite frustrating. To avoid this, move the cancel button to another position, like to the left of pagemaintitletext:
dojo.place('button_unpass', 'pagemaintitletext', 'before');
Being out of the generalactions div, it won't be automatically destroyed like normal buttons, so you'll have to handle that yourself in onLeavingState. You might also want to change the button color to red (blue buttons for active player only, red buttons also for inactive players?)

Note: same technique can be used to do other out-of-turn actions, such as re-arranging cards in hand, exchanging resources, etc (i.e. if permitted by rules, such as "at any time player can...")

=== Multi Step Interactions: Select Worker/Place Worker - Using Selection ===

'''Ingredients:''' ggg.js

Simple way to implement something like that without extra states is to use "selection" mechanism. When user click on worker add some sort of class into that element i.e. 'selected' (which also have to have some indication by css i.e. outline).

Than user can click on placement zone, you can use dojo.query for "selected" element and use it along with zone id to send data to server. If proper worker is not selected yet can give a error message using this.showMessage(...) function.

Extra code required to properly cleanup selection between states.
Also when you do that sometimes you want to change the state prompt, see below 'Change state prompt'

=== Multi Step Interactions: Select Worker/Place Worker - Using Client States ===

'''Ingredients:''' ggg.js

I don't think its documented feature but there is a way to do client-only states, which is absolutely wonderful for few reasons
* When player interaction is two step process, such as select worker, place worker, or place worker, pick one of two resources of your choice
* When multi-step process can result of impossible situation and has to be undone (by rules)
* When multi-step process is triggered from multiple states (such as you can do same thing as activated card action, pass action or main action)

So lets do Select Worker/Place Worker

Define your server state as usual, i.e. playerMainTurn -> "You must pick up a worker".
Now define a client state, we only need "name" and "descriptionmyturn", lets say "client_playerPicksLocation". Always prefix names of client state with "client_" to avoid confusion. Now we have to do the following:
* Have a handler for onUpdateActionButtons for playerMainTurn to activate all possible workers he can pick
* When player clicks workers, remember the worker in one of the members of the main class, I usually use one called this.clientStateArgs.
* Transition to new client state
onWorker: function(e) {
var id = event.currentTarget.id;
dojo.stopEvent(event);
... // do validity checks
this.clientStateArgs.worker_id = id;
this.setClientState("client_playerPicksLocation", {
descriptionmyturn : _("${you} must select location"),
});
}
* Have a handler for onUpdateActionButtons for client_playerPicksLocation to activate all possible locations this worker can go AND add Cancel button (see below)
* Have a location handler which will eventually send a server request, using stored this.clientStateArgs.worker_id as worker id
* The cancel button should call a method to restore server state, also if you doing it for more than one state you can add this universally using this.on_client_state check

if (this.isCurrentPlayerActive()) {
if (this.on_client_state && !$('button_cancel')) {
this.addActionButton('button_cancel', _('Cancel'), dojo.hitch(this, function() {
this.restoreServerGameState();
}));
}
}
Note: usually I call my own function call this.cancelLocalStateEffects() which will do more stuff first then call restoreServerGameState(), same function is usually needs to be called when server request has failed (i.e. invalid move)

Note: If you need more than 2 steps, you may have to do client side animation to reflect the new state, which gets trickier because you have to undo that also on cancellation.

Code is available here [https://github.com/elaskavaia/bga-sharedcode/blob/master/sharedcode.js sharedcode.js] (its using playerTurnPlayCubes and client_selectCubeLocation).

=== Action Stack - Using Client States ===

Action stack required where game is very complex and use triggered effects that can "stack". It not always actual stack, it can be queue or random access
Examples:
* Magic the Gathering - classic card game where effects go on Stack, that allows to counter spell and counter spell of counter spell (not on bga - it just example of mechanics)
* Ultimate Railroads - action taking game where effects can be executed in any order
* Lewis and Clark - card game where actions executed as queue

There is two ways of implementing it - on the server or the client.
For the server see article below.
The requirement for client side stack implementation is - all action can be undone, which means
* No dice rolls
* No card drawn
* No other players interaction

No snippets are here, as this will be too complex but basically flow is:
* You have a action/effect stack (queue/list) as js object attached to "this", i.e. this.unprocessed_actions
* When player plays a card, worker, etc, you read the effect of that card from the material file (client copy), and place into stack
* Then we call dispatch method which pulls the next action from the stack and change client state accordinly, i.e. this.setClientState("client_playerGainsCubes")
* When players acts on it - the action is removed from the stack and added to "server action arguments" list, this is another object which be used to send ajax call, i.e. this.clientStateArgs
* If nothing left in stack we can submit the ajax call assembling parameters from collected arguments (that can include action name)
* This method allows cheap undo - by restoring server state you will wipe out all user actions (but if you need intermediate aninmation you have to handle it yourself)

Code can be found in Ultimate Railroads game (but it is random access list - so it a bit complex) and Lewis and Clark (complexity - user can always deny part of any effect)

=== Action Stack - Using Server States ===

See definition of Action Stack above.

To implement you usually need another db table that has the following fields: index of effect - which is used for sorted access, type - which is essense of the effect (i.e. collect resource), some extra arguments (i.e. resource type and resource count), and usually owner of the effect (i.e. player id)
The flow is:
* There is some initial player state, where player can play card for example
* Player main action - pushes the card effect on stack, which also can cause triggered effects which also go on stack
* After action processing is finished switch to game state which is "dispatcher"
* Dispatcher pulls the top effect (whatever definition of the top is), changes the active player and changes the state to appropriate player state to collect response. The "top" can be choice of multiple actions, in this case player has to chose one before resolving the effect.
* Player state knows about the stack and pulls arguments (argX) from the effect arguments of the db
* Player action should clear up the top effect, and can possibly add more effects, then switch to "dispatcher" state again
* If stack is empty, dispatcher can either pick next player itself or use another game state which responsible for picking next player

Code can be found in Tapestry and Terraforming Mars.
=== Custom error/exception handling in JavaScript ===

; In ggg.php
Throw BgaUserException with some easy-to-identify prefix such as "!!!" and a custom error code. DO NOT TRANSLATE this message text. The exception will rollback database transaction and cancel all changes (including any notifications).
<pre>
function foo(bool $didConfirm = false): void
{
// do processing for the user's move
// afterwards, you determine this move will end the game
// so you want to rollback the transaction and require the user to confirm the move first

if ($gameIsEnding && !$didConfirm) {
throw new BgaUserException('!!!endGameConfirm', 9001);
}
}
</pre>

; In ggg.js
Override framework function showMessage to suppress the red banner message and gamelog message when you detect the "!!!" prefix
<pre>
/* @Override */
showMessage: function (msg, type) {
if (type == "error" && msg && msg.startsWith("!!!")) {
return; // suppress red banner and gamelog message
}
this.inherited(arguments);
},
</pre>

Deal with the error in your callback:
<pre>
fooAction: function (didConfirm) {
var data = {
foo: "bar",
didConfirm: !!didConfirm,
};
this.bgaPerformAction("fooAction", data).catch((error, errorMsg) => {
if (error && errorMsg == "!!!endGameConfirm") {
// your custom error handling goes here
// for example, show a confirmation dialog and repeat the action with additional param
this.confirmationDialog(
_("Doing the foo action now will end the game"),
() => this.fooAction(true)
);
}
});
},
</pre>

For custom global error handling, you could modify ajaxcallwrapper:
<pre>
ajaxcallwrapper: function (action, args, handler) {
if (!args) args = {};
args.lock = true;
args.version = this.gamedatas.version;
if (this.checkAction(action)) {
this.bgaPerformAction(
action,
args
).catch((error, errorMsg, errorCode) => {
if (error && errorMsg == "!!!checkVersion") {
this.infoDialog(
_("A new version of this game is now available"),
_("Reload Required"),
() => {
window.location.reload();
},
true
);
} else {
if (handler) handler(error, errorMsg, errorCode);
}
}
);
}
},
</pre>

=== Force players to refresh after new deploy ===

When you deploy a new version of your game, the PHP backend code is immediately updated but the JavaScript/HTML/CSS frontend code *does not update* for active players until they manually refresh the page (F5) in their browser. Obviously this is not ideal. In the best case, real-time tables don't see your shiny new enhancements. In the worst case, your old JS code isn't compatible with your new PHP code and the game breaks in strange ways (any bug reports filed will be false positives and unable to reproduce). To avoid any problems, you should force all players to immediately reload the page following a new deploy.

By throwing a "visible" exception (simplest solution), you'll get something like this which instructs the user to reload:

[[File:Force-refresh.png|950x950px]]

Or, if you combine this technique with the above custom error handling technique, you could do something a bit nicer. You could show a dialog box and automatically refresh the page when the user clicks "OK":

[[File:Reload-required.png|500x500px]]
; In ggg.php
Transmit the server version number in <code>getAllDatas()</code>.
<pre>
protected function getAllDatas(): array
{
$players = $this->getCollectionFromDb("SELECT player_id id, player_score score FROM player");
return [
'players' => $players,
'version' => intval($this->gamestate->table_globals[300]), // <-- ADD HERE
...
];
}
</pre>

Create a helper function to fail if the client and server versions mismatch. Note the version check uses <code>!=</code> instead of <code><</code> so it can support rollback to a previous deploy as well. ;-)
<pre>
public function checkVersion(int $clientVersion): void
{
if ($clientVersion != intval($this->gamestate->table_globals[300])) {
// Simplest way is to throw a "visible" exception
// It's ugly but comes with a "click here" link to refresh
throw new BgaVisibleSystemException($this->_("A new version of this game is now available. Please reload the page (F5)."));

// For something prettier, throw a "user" exception and handle in JS
// (see BGA cookbook section above on custom error handling)
throw new BgaUserException('!!!checkVersion');
}
}
</pre>
; In ggg.action.php
Create a helper function for actions:
<pre>
private function checkVersion()
{
$clientVersion = (int) $this->getArg('version', AT_int, false);
$this->game->checkVersion($clientVersion);
}
</pre>

Call <code>$this->checkVersion()</code> at the top of <b>every action function</b>, immediately after <code>$this->setAjaxMode()</code>:
<pre>
public function move()
{
$this->setAjaxMode();
$this->checkVersion(); // <-- ADD HERE
...
$this->ajaxResponse();
}
</pre>

; In ggg.js
Transmit the version (from gamedatas) as a parameter with every ajax call. For example, if you're already using a wrapper function for every ajax call, add it like this:
<pre>
ajaxcallwrapper: function (action, args) {
if (!args) args = {};
args.version = this.gamedatas.version; // <-- ADD HERE
this.bgaPerformAction(action, args);
},
</pre>

=== Disable / lock table creation for new deploy ===

If you are deploying a major new game version, especially if it involves upgrading production game databases, you may have a lot of angry players if you break their tables. Depending on your changes, you may be able to restore the previous version and fix the tables easily.

However, if a new deploy turns out bad and players created turn-based tables while it was live, it may be quite difficult to fix those tables, since they were created from a bad deploy.

The solution? You can announce in your game group that you are locking table creation, and then in your new version, add an impossible startcondition to an existing option.
Note: This only makes sense if you have a few games running in real time mode in the time of deployment, otherwise it won't achieve much, unless you wait at least a day for other turn based games to break (or not)

Here is an example of an option with only 2 values (if you don't have options at all you have to create a fake option to use this method, if you have more values - you have to list them all):

; In gameoptions.json
<pre>
"startcondition": {
"0": [ { "type": "minplayers", "value": 32, "message": "Maintenance in progress. Table creation is disabled." } ],
"1": [ { "type": "minplayers", "value": 32, "message": "Maintenance in progress. Table creation is disabled." } ]
},
</pre>
; In gameoptions.inc.php (older method if you have it in php)
<pre>
// TODO NEXT remove after testing deploy to upgrade, here 0 and 1 - replace with values of your option!
'startcondition' => [
0 => [ [ 'type' => 'minplayers', 'value' => 32, 'message' => totranslate('Maintenance in progress. Table creation is disabled.') ] ],
1 => [ [ 'type' => 'minplayers', 'value' => 32, 'message' => totranslate('Maintenance in progress. Table creation is disabled.') ] ],
],
</pre>

* Be sure to click "Reload game options configuration" after making this change, then test in studio (test that you cannot create any table)
* Deploy to production
* Now, when a player attempts to create a new table, they will see a red error bar with your "Maintenance in progress" message.
* Wait for screaming (if you have real times games in progress waiting 15 min probably ok, if you have only turn based games, probably a day)
* Once you confirm the new deploy looks good, you can revert the change in gameoptions.inc.php and do another deploy.

=== Local Storage ===

There is not much you can store in localStorage (https://developer.mozilla.org/docs/Web/API/Window/localStorage), since most stuff should be stored either in game db or in user prefrences,
but some stuff makes sense to store there, for example "zoom" level (if you use custom zooming). This setting really affect this specific host and specific browser, setting it localStorage makes most sense.

game.js
<pre>
setup: function (gamedatas) {
let zoom = localStorage.getItem(`${this.game_name}_zoom`);
this.setZoom(zoom);
...
},
</pre>
In this case setZoom is custom function to actually set it.
When zoom changed, for example when some buttons pressed, store current value (but sanitize it so it never so bad that game cannot be viewed

<pre>
setZoom: function (zoom) {
zoom = parseInt(zoom) || 0;
if (zoom === 0 || zoom < 0.1 || zoom > 10) {
zoom = 1;
}
this.zoom = zoom;
localStorage.setItem(`${this.game_name}_zoom`, "" + this.zoom);
... do actual zooming stuff
},
</pre>

=== Capture client JavaScript errors in the "unexpected error" log ===

PHP (backend) errors are recorded in the "unexpected error" log, but JavaScript (frontend) errors are only available in the browser itself. This means you have no visibility about things that go wrong in the client... unless you make clients report their errors to the server.

; In actions.php:
<pre>
public function jsError()
{
$this->setAjaxMode(false);
$this->game->jsError($_POST['userAgent'], $_POST['msg']);
$this->ajaxResponse();
}
</pre>

; In game.php:
<pre>
public function jsError($userAgent, $msg): void
{
$this->error("JavaScript error from User-Agent: $userAgent\n$msg // ");
}
</pre>

; In game.js:
<pre>
define(["dojo", "dojo/_base/declare", "ebg/core/gamegui", "ebg/counter"], function (dojo, declare) {
const uniqJsError = {};
...

return declare("bgagame.nowboarding", ebg.core.gamegui, {
...
/* @Override */
onScriptError(msg) {
if (!uniqJsError[msg]) {
uniqJsError[msg] = true;
console.error("⛔ Reporting JavaScript error", msg);
this.ajaxcall(
"/" + this.game_name + "/" + this.game_name + "/jsError.html",
{
msg,
userAgent: navigator.userAgent,
},
this,
() => {},
() => {},
"post"
);
}
this.inherited(arguments);
},
</pre>

== Algorithms ==

=== Generate permutations in lexicographic order ===

Use this when you have an array like [1, 2, 3, 4] and need to loop over some/all 24 permutations of possible ordering. This type of [https://www.php.net/manual/en/language.generators.syntax.php generator function] computes each possibility one at a time, making it vastly more efficient than either a normal iteration or recursive function that produce all possibilities up front.

<pre>
function generatePermutations(array $array): Generator
{
// https://en.wikipedia.org/wiki/Permutation#Generation_in_lexicographic_order
// Sort the array and this is the first permutation
sort($array);
yield $array;

$count = count($array);
do {
// Find the largest index k where a[k] < a[k + 1]
// End when no such index exists
$found = false;
for ($k = $count - 2; $k >= 0; $k--) {
$kvalue = $array[$k];
$knext = $array[$k + 1];
if ($kvalue < $knext) {
// Find the largest index l greater than k where a[k] < a[l]
for ($l = $count - 1; $l > $k; $l--) {
$lvalue = $array[$l];
if ($kvalue < $lvalue) {
// Swap a[k] and a[l]
[$array[$k], $array[$l]] = [$array[$l], $array[$k]];

// Reverse the sequence from a[k + 1] up to and including the final element
$reverse = array_reverse(array_slice($array, $k + 1));
array_splice($array, $k + 1, $count, $reverse);
yield $array;

// Restart with the new array to find the next permutation
$found = true;
break 2;
}
}
}
}
} while ($found);
}
</pre>

Usage:
<pre>
$cash = [4, 1, 2, 3, 4];
foreach ($this->generatePermutations($cash) as $p) {
// your code here to evaluate permutation $p
// first iteration: $p = [1, 2, 3, 4, 4]
// last (60th) iteration: $p = [4, 4, 3, 2, 1]
// break from loop once you achieve your goal
}
</pre>

[[Category:Studio]]

BGA Studio Cookbook

2024-09-24T14:30:28Z

Sguzzer Gunayer: /* Using CSS to create different colors of game pieces if you have only white piece */

This page is a cookbook of design and implementation recipes for BGA Studio framework.
For tooling and usage recipes see [[Tools and tips of BGA Studio]].
If you have your own recipes feel free to edit this page.

__TOC__

== Visual Effects, Layout and Animation ==

=== DOM manipulatons ===

==== Create pieces dynamically (using template) ====

'''Ingredients:''' ggg_ggg.tpl, ggg.js

Note: this method is recommended by BGA guildlines

Declared js template with variables in .tpl file, like this
<pre>
<script type="text/javascript">
// Javascript HTML templates
var jstpl_ipiece = '<div class="${type} ${type}_${color} inlineblock" aria-label="${name}" title="${name}"></div>';
</script>
</pre>

Use it like this in .js file
div = this.format_block('jstpl_ipiece', {
type : 'meeple',
color : 'ff0000',
name : 'Bob',
});

Then you do whatever you need to do with that div, this one specifically design to go to log entries, because it has embedded title (otherwise its a picture only) and no id.

Note: you could have place this variable in js itself, but keeping it in .tpl allows you to have your js code be free of HTML. Normally it never happens but
it is good to strive for it.
Note: you can also use string concatenation, its less readable. You can also use dojo dom object creation api's but its brutally verbose and its more unreadable.

==== Create pieces dynamically (using string concatenation) ====

'''Ingredients:''' ggg.js

<pre>
div = "<div class='meeple_"+color+"'></div>";
</pre>

or modern way

<pre>
div = `<div class='meeple_${color}'></div>`;
</pre>

==== Create all pieces statically ====

'''Ingredients:''' ggg_ggg.tpl, ggg.css, ggg.view.php (optional)

* Create ALL game pieces in html template (.tpl)
* ALL pieces should have unique id, and it should be meaningful, i.e. meeple_red_1
* Do not use inline styling
* Id of player's specific pieces should use some sort of 'color' identification, since player id cannot be used in static layout, you can use english color name, hex 6 char value, or color "number" (1,2,3...)
* Pieces should have separated class for its color, type, etc, so it can be easily styled in groups. In example below you now can style all meeples, all red meeples or all red tokens, or all "first" meeples

ggg.tpl:
<pre>
<div id="home_red" class="home_red home">
<div id="meeple_red_1" class="meeple red n1"></div>
<div id="meeple_red_2" class="meeple red n2"></div>
</div>
</pre>

ggg.css:

<pre>
.meeple {
width: 32px;
height: 39px;
background-image: url(img/78_64_stand_meeples.png);
background-size: 352px;
}

.meeple.red {
background-position: 30% 0%;
}
</pre>

* There should be straight forward mapping between server id and js id (or 1:1)
* You place objects in different zones of the layout, and setup css to take care of layout

<pre>
.home .meeple{
display: inline-block;
}
</pre>
* If you need to have a temporary object that look like original you can use dojo.clone (and change id to some temp id)
* If there is lots of repetition or zone grid you can use template generator, but inject style declaration in css instead of inline style for flexibility

Note:
* If you use this model you cannot use premade js components such as Stock and Zone
* You have to use alternative methods of animation (slightly altered) since default method will leave object with inline style attributes which you don't need

==== Use player color in template ====

'''Ingredients:''' ggg_ggg.tpl, ggg.view.php

.view.php:
<pre>
function build_page($viewArgs) {
// Get players & players number
$players = $this->game->loadPlayersBasicInfos();
$players_nbr = count($players);
/**
* ********* Place your code below: ***********
*/

// Set PCOLOR to the current player color hex
global $g_user;
$cplayer = $g_user->get_id();
if (array_key_exists($cplayer, $players)) { // may be not set if spectator
$player_color = $players [$cplayer] ['player_color'];
} else {
$player_color = 'ffffff'; // spectator
}
$this->tpl ['PCOLOR'] = $player_color;
</pre>

=== Status bar ===

==== Changing state prompt ====

State prompt is message displayed for player which usually comes from state description.
Sometimes you want to change it without changing state (one way is change state but locally, see client states above).

Simple way just change the html
<pre>
setMainTitle: function(text) {
$('pagemaintitletext').innerHTML = text;
},
// usage
onMeeple: function(event) {
//...
this.setMainTitle(_('You must select where meeple is going'));
},
</pre>

This however will not work with parameters and will not draw You in color, if you want this its more sophisticated:

<pre>
setDescriptionOnMyTurn : function(text) {
this.gamedatas.gamestate.descriptionmyturn = text;
var tpl = dojo.clone(this.gamedatas.gamestate.args);
if (tpl === null) {
tpl = {};
}
var title = "";
if (this.isCurrentPlayerActive() && text !== null) {
tpl.you = this.divYou();
}
title = this.format_string_recursive(text, tpl);

if (!title) {
this.setMainTitle(" ");
} else {
this.setMainTitle(title);
}
},
</pre>

Note: this method uses '''setMainTitle''' defined above and '''divYou''' defined in another section of this wiki.

=== Animation ===

==== Attach to new parent without destroying the object ====

BGA function attachToNewParent for some reason destroys the original, if you want similar function that does not you can use this
ggg.js

<pre>
/**
* This method will attach mobile to a new_parent without destroying, unlike original attachToNewParent which destroys mobile and
* all its connectors (onClick, etc)
*/
attachToNewParentNoDestroy: function (mobile_in, new_parent_in, relation, place_position) {

const mobile = $(mobile_in);
const new_parent = $(new_parent_in);

var src = dojo.position(mobile);
if (place_position)
mobile.style.position = place_position;
dojo.place(mobile, new_parent, relation);
mobile.offsetTop;//force re-flow
var tgt = dojo.position(mobile);
var box = dojo.marginBox(mobile);
var cbox = dojo.contentBox(mobile);
var left = box.l + src.x - tgt.x;
var top = box.t + src.y - tgt.y;

mobile.style.position = "absolute";
mobile.style.left = left + "px";
mobile.style.top = top + "px";
box.l += box.w - cbox.w;
box.t += box.h - cbox.h;
mobile.offsetTop;//force re-flow
return box;
},
</pre>

==== Animation on oversurface ====
If you use non-absolute position for your game elements (i.e you use layouts) - you cannot really use BGA animation functions. After years of fidding with different options I use
techique which I call animation on oversurface that works when parents use different zoom, rotation, etc

* You need another layer on top of everything - oversurface
* We create copy of the object on oversurface - to move
* We move the real object on final position - but make it invisible for now
* We move the phantom to final position applying required zoom and rotation (using css animation), then destroy it
* When animation is done we make original object visible in new position

The code is bit complex it can be found here

https://codepen.io/VictoriaLa/pen/gORvdJo

Game using it: century, ultimaterailroads

==== Scroll element into view ====
Ingredients: game.js

This function will scroll given node (div) into view and respect replays and archive mode

<pre>
scrollIntoViewAfter: function (node, delay) {
if (this.instantaneousMode || this.inSetup) {
return;
}
if (typeof g_replayFrom != "undefined") {
$(node).scrollIntoView();
return;
}
if (!delay) delay = 0;
setTimeout(() => {
$(node).scrollIntoView({ behavior: "smooth", block: "center" });
}, delay);
},
</pre>

=== Logs ===

==== Inject icon images in the log ====

Here is an example of what was done for Terra Mystica which is simple and straightforward:

<pre>
//Define the proper message
$message = clienttranslate('${player_name} gets ${power_income} via Structures');
if ($price > 0) {
$this->DbQuery("UPDATE player SET player_score = player_score - $price WHERE player_id = $player_id");
$message = clienttranslate('${player_name} pays ${vp_price} and gets ${power_income} via Structures');
}

// Notify
$this->notifyAllPlayers( "powerViaStructures", $message, array(
'i18n' => array( ),
'player_id' => $player_id,
'player_name' => $this->getUniqueValueFromDb( "SELECT player_name FROM player WHERE player_id = $player_id" ),
'power_tokens' => $power_tokens,
'vp_price' => $this->getLogsVPAmount($price),
'power_income' => $this->getLogsPowerAmount($power_income),
'newScore' => $this->getUniqueValueFromDb( "SELECT player_score FROM player WHERE player_id = $player_id" ),
'counters' => $this->getGameCounters(null),
) );
</pre>

With some functions to have the needed html added inside the substitution variable, such as:

<pre>
function getLogsPowerAmount( $amount ) {
return "<div class='tmlogs_icon' title='Power'><div class='power_amount'>$amount</div></div>";
}
</pre>
Note: injecting html from php is not ideal but easy, if you want more clean solution, use method below but it is a lot more sophisticated.

==== Inject images and styled html in the log ====

{{InfoBox|title=Warning — Translation|maxWidth=500|color=#c00|body='''In order to prevent interference with the translation process, keep in mind that you must only apply modifications to the args object, and not try to substitute the keys (the <code>${player_name}</code> parts of your string) in the log string.'''}}

So you want nice pictures in the game log. What do you do? The first idea that comes to mind is to send html from php in notifications (see method above).

This is a bad idea for many reasons:

* It's bad architecture. ui elements leak into the server, and now you have to manage the ui in multiple places.
* If you decided to change something in the ui in future version, replay logs for old games and tutorials may not work, since they use stored notifications.
* Log previews for old games become unreadable. (This is the log state before you enter the game replay, which is useful for troubleshooting and game analysis.)
* It's more data to transfer and store in the db.
* It's a nightmare for translators.

So what else can you do? You can use client side log injection to intercept log arguments (which come from the server) and replace them with html on the client side. Here are three different method you can use to achieve this.

===== Override <code>this.format_string_recursive()</code> method =====

'''Ingredients:''' ggg.js, ggg.game.php

I use this recipe for '''client side log injection''' to intercept log arguments (which come from the server) and replace them with html on the client side.

[[File:clientloginjection.png|left]]

ggg.js

<pre>

/** Override this function to inject html into log items. This is a built-in BGA method. */

/* @Override */
format_string_recursive : function format_string_recursive(log, args) {
try {
if (log && args && !args.processed) {
args.processed = true;

// list of special keys we want to replace with images
var keys = ['place_name','token_name'];

for ( var i in keys) {
var key = keys[i];
key in args && args[key] = this.getTokenDiv(key, args);

}
}
} catch (e) {
console.error(log,args,"Exception thrown", e.stack);
}
return this.inherited({callee: format_string_recursive}, arguments);
},
</pre>

'''Important:''' In the ''format_string_recursive'' method, the 'args' parameter will only contain arguments passed to it from the notify method in ggg.game.php (see below).

The 'log' parameter is the actual string that is inserted into the logs. You can perform additional js string manipulation on it.

<pre>
getTokenDiv : function(key, args) {
// ... implement whatever html you want here, example from sharedcode.js
var token_id = args[key];
var item_type = getPart(token_id,0);
var logid = "log" + (this.globalid++) + "_" + token_id;
switch (item_type) {
case 'wcube':
var tokenDiv = this.format_block('jstpl_resource_log', {
"id" : logid,
"type" : "wcube",
"color" : getPart(token_id,1),
});
return tokenDiv;

case 'meeple':
if ($(token_id)) {
var clone = dojo.clone($(token_id));

dojo.attr(clone, "id", logid);
this.stripPosition(clone);
dojo.addClass(clone, "logitem");
return clone.outerHTML;
}
break;

default:
break;
}

return "'" + this.clienttranslate_string(this.getTokenName(token_id)) + "'";
},
getTokenName : function(key) {
return this.gamedatas.token_types[key].name; // get name for the key, from static table for example
},
</pre>

Note that in this case the server simply injects token_id as a name, and the client substitutes it for the translated name or the picture.

ggg.game.php:

$this->notifyAllPlayers('playerLog',clienttranslate('Game moves ${token_name}'),['token_name'=>$token_id]);

'''Important:''' As noted above, only arguments actually passed by this method are available to the args parameter received in the client-side ''format_string_recursive'' method.

Sometimes it is the case that you want to pass arguments that are not actually included in the output message. For example, suppose we have a method like this:

$this->notifyAllPlayers('tokenPlaced',clienttranslate('Player placed ${token_name}'),array(
'token_name' => $token_id,
'zone_played' => $zone);

This will output "Player placed ${token_name}" in the log, and if we subscribe to a notification method activated by the "tokenPlaced" event in the client-side code, that method can make use of the 'zone_played' argument.

Now if you want to make some really cool things with game log, most probably you would need more arguments than are included in log message. The problem with that,
it will work at first, but if you reload game using F5 or when the game loads in turn based mode, you will loose your additional parameters, why? Because when game reloads it does not actually send same notifications, it sends special "hitstorical_log" notification where all parameters not listed in the message are removed. In example above, field zone_played would be removed from historical log as it is not included in message of the notification. You can till preserve specific arguments in historical log by adding special field preserve to notification arguments like this:

<pre>
$this->notifyAllPlayers('tokenPlaced',clienttranslate('Player placed ${token_name}'),array(
'token_name' => $token_id,
'zone_played' => $zone,
'preserve' => [ 'zone_played' ]
);
</pre>

Now you can use zone_played in format_string_recursive even in historical logs.

===== Use <code>:formatFunction</code> option provided by <code>dojo.string.substitute</code> =====

'''Ingredients:''' ggg.js, ggg.game.php, ggg_ggg.tpl, ggg.css

The above method will work in most of the cases, but if you use dotted keys such as <code>${card.name}</code> (which is supported by the framework, for private state args), the key won't be substituted because the <code>key in arg</code> test will fail. If so you need to rely either on this way, or the one after.

'''WARNING:''' using this method on an already advanced project will require you to go through all your notifications to change keys !

Under the hood, the '''this.format_string_recursive()''' function calls the '''dojo.string.substitute''' method which substitutes <code>${keys}</code> with the value provided. If you take a look at the [https://dojotoolkit.org/reference-guide/1.7/dojo/string.html#substitute documentation] and [https://github.com/dojo/dojo/blob/c3ceb017cfa25b703f5662dc83d1c8aae9bc5d81/string.js#L163 source code] you can notice that the key can be suffixed with a colon (<code>:</code>) followed by a function name. This will allow you to specify directly in the substitution string which keys need HTML injection.

First of all, you need to define your formatting function in the ggg.js file:
<pre>
[[ggg.js]]
getTokenDiv : function(value, key) {
//This is only an example implementation, you need to write your own.
//The method should return HTML code
switch (key) {
case 'html_injected_argument1':
return this.format_block('jstpl_HTMLLogElement1',{value: value});
case 'html_injected_argument2':
return this.format_block('jstpl_HTMLLogElement2',{value: value});
...
}
}
</pre>

Obviously you need to define the appropriate templates in the ggg_ggg.tpl file:
<pre>
[[ggg_ggg.tpl]]
let jstpl_HTMLLogElement1 = '<div class="log-element log-element-1-${value}"></div>';
let jstpl_HTMLLogElement2 = '<div class="log-element log-element-2-${value}"></div>';
...
</pre>
And the appropriate classes in ggg.css.

Then you need to add the <code>dojo/aspect</code> module at the top of the ggg.js file:

<nowiki>[[ggg.js]]</nowiki>
define([
"dojo", "dojo/_base/declare",
'''<span style="color:green;">"dojo/aspect",</span> //MUST BE IN THIRD POSITION''' (see [[#Including your own JavaScript module (II)|below]])
"ebg/core/gamegui",
"ebg/counter",
], function (dojo, declare, <span style="color:green;">'''aspect'''</span>) {
...

And you also need to add the following code in your <code>contructor</code> method in the ggg.js:

<nowiki>[[ggg.js]]</nowiki>
constructor: function(){

// ... skipped code ...
let gameObject = this; //Needed as the this object in aspect.before will not refer to the game object in which the formatting function resides
aspect.before(dojo.string, "substitute", function(template, map, transform) { //This allows you to modify the arguments of the dojo.string.substitute method before they're actually passed to it
return [template, map, transform, gameObject];
});

Now you're all set to inject HTML in your logs. To actually achieve this, you must specify the function name with the key like so:

<nowiki>[[ggg.game.php]]</nowiki>
$this->notifyAllPlayers("notificationName", clienttranslate("This log message contains ${plainTextArgument} and the following will receive HTML injection: ${html_injected_argument1:getTokenDiv}"), [
"plainTextArgument" => "some plain text here",
"html_injected_argument1" => "some value used by getTokenDiv",
]);

You're not limited writing only one function, you can write as many functions as you like, and have them each inject a specific type of HTML. You just need to specify the relevant function name after the column in the substitution key.

===== Use <code>transform</code> argument of <code>dojo.string.substitute</code> =====

'''Ingredients:''' ggg.js, ggg.game.php, ggg_ggg.tpl, ggg.css

This method is also relying on the use of <code>dojo.string.substitute</code> by the framework, and will use the <code>transform</code> argument, which, accordting to [https://github.com/dojo/dojo/blob/c3ceb017cfa25b703f5662dc83d1c8aae9bc5d81/string.js#L163 source code] and [https://dojotoolkit.org/reference-guide/1.7/dojo/string.html#substitute documentation] will be run on all the messages going through dojo.string.substitute.

'''WARNING:''' This method will be applied to all strings that go through dojo.string.substitute. As such you must take extra care not to substitute keys that may be used by the framework (i.e. ${id}). In order to do so, a good practise would be to prefix all keys that need substitution with a trigram of the game name.

Since all the keys will be fed to the tranform function, by default, it must return the value, substituted or not per your needs. You can define the function like this in the ggg.js file:

<nowiki>[[ggg.js]]</nowiki>
getTokenDiv : function(value, key) {
//This is only an example implementation, you need to write your own.
//The method should return HTML code
switch (key) {
case 'html_injected_argument1':
return this.format_block('jstpl_HTMLLogElement1',{value: value});
case 'html_injected_argument2':
return this.format_block('jstpl_HTMLLogElement2',{value: value});
...
default:
return value; //Needed otherwise regular strings won't appear since since the value isn't returned by the function
}
}

The templates must be defined in the ggg_ggg.tpl file and the corresponding CSS classes in the ggg.css file.

You need to add the following code at the beginning of the ggg.js file:

<nowiki>[[ggg.js]]</nowiki>
define([
"dojo", "dojo/_base/declare",
'''<span style="color:green;">"dojo/aspect",</span> //MUST BE IN THIRD POSITION''' (see [[#Including your own JavaScript module (II)|below]])
"ebg/core/gamegui",
"ebg/counter",
], function (dojo, declare, <span style="color:green;">'''aspect'''</span>) {
...

And the following code to the <code>constructor</code> method in ggg.js:

<nowiki>[[ggg.js]]</nowiki>
constructor: function(){
// ... skipped code ...
let transformFunction = dojo.hitch(this, "getTokenDiv"); //Needed as the this object in aspect.before will not refer to the game object in which the formatting function resides
aspect.before(dojo.string, "substitute", function(template, map, transform) {
if (undefined === transform) { //Check for a transform function presence, just in case
return [template, map, transformFunction];
}
});

Then you're all set for log injection, no need to change anything on the PHP side.

==== Processing logs on re-loading ====

You rarely need to process logs when reloading, but if you want to do something fancy you may have to do it after logs are loaded.
Logs are loaded asyncronously so you have to listen for logs to be fully loaded.
Unfortunately there is no direct way of doing it so this is the hack.

'''Hack alert''' - this extends undocumented function and may be broken when framework is updated

'''Ingredients:''' ggg.js

<pre>
/*
* [Undocumented] Override BGA framework functions to call onLoadingLogsComplete when loading is done
@Override
*/
setLoader: function(image_progress, logs_progress) {
this.inherited(arguments); // required, this is "super()" call, do not remove
//console.log("loader", image_progress, logs_progress)
if (!this.isLoadingLogsComplete && logs_progress >= 100) {
this.isLoadingLogsComplete = true; // this is to prevent from calling this more then once
this.onLoadingLogsComplete();
}
},

onLoadingLogsComplete: function() {
console.log('Loading logs complete');
// do something here
},
</pre>

=== Player Panel ===

==== Inserting non-player panel ====

'''Ingredients:''' ggg.js, ggg_ggg.tpl

If you want to insert non-player panel on the right side (for example to hold extra preferences, zooming controls, etc)

this can go pretty much anywhere in template it will be moved later

ggg_ggg.tpl:
<pre>
<div class='player_board_config' id="player_board_config">

<button id="zoom-out" class=" fa fa-search-minus fa-2x config-control"></button>
<button id="zoom-in" class=" fa fa-search-plus fa-2x config-control"></button>
<button id="show-settings" class="fa fa-cog fa-2x config-control "></button>
</div>
</pre>

some hackery required in js

ggg.js:
<pre>
/* @Override */
updatePlayerOrdering() {
this.inherited(arguments);
dojo.place('player_board_config', 'player_boards', 'first');
},
</pre>

=== Images and Icons ===

==== Accessing images from js ====

'''Ingredients:''' ggg.js

<pre>
// your game resources

var my_img = '<img src="'+g_gamethemeurl+'img/cards.jpg"/>';

// shared resources
var my_help_img = "<img class='imgtext' src='" + g_themeurl + "img/layout/help_click.png' alt='action' /> <span class='tooltiptext'>" +
text + "</span>";
</pre>

==== High-Definition Graphics ====

Some users will have screens which can display text and images at a greater resolution than the usual 72 dpi, e.g. the "Retina" screens on the 5k iMac, all iPads, and high-DPI screens on laptops from many manufacturers. If you can get art assets at this size, they will make your game look extra beautiful. You ''could'' just use large graphics and scale them down, but that would increase the download time and bandwidth for users who can't display them. Instead, a good way is to prepare a separate graphics file at exactly twice the size you would use otherwise, and add "@2x" at the end of the filename, e.g. if pieces.png is 240x320, then pieces@2x.png is 480x640.

There are two changes required in order to use the separate graphics files. First in your css, where you use a file, add a media query which overrides the original definition and uses the bigger version on devices which can display them. Ensuring that the "background-size" attribute is set means that the size of the displayed object doesn't change, but only is drawn at the improved dot pitch.
<pre>
.piece {
position: absolute;
background-image: url('img/pieces.png');
background-size:240px 320px;
z-index: 10;
}
@media (-webkit-min-device-pixel-ratio: 2), (min-device-pixel-ratio: 2), (min-resolution: 192dpi)
{
.piece {
background-image: url('img/pieces@2x.png');
}
}
</pre>

Secondly, in your setup function in javascript, you must ensure than only the appropriate one version of the file gets pre-loaded (otherwise you more than waste the bandwidth saved by maintaining the standard-resolution file). Note that the media query is the same in both cases:
<pre>
var isRetina = "(-webkit-min-device-pixel-ratio: 2), (min-device-pixel-ratio: 2), (min-resolution: 192dpi)";
if (window.matchMedia(isRetina).matches)
{
this.dontPreloadImage( 'pieces.png' );
this.dontPreloadImage( 'board.jpg' );
}
else
{
this.dontPreloadImage( 'pieces@2x.png' );
this.dontPreloadImage( 'board@2x.jpg' );
}
</pre>

==== Using CSS to create different colors of game pieces if you have only white piece ====

<pre>
background-color: #${color};
background-blend-mode: multiply;
background-image: url( 'img/mypiece.png');
mask: url('img/mypiece.png');
-webkit-mask: url('img/mypiece.png');
</pre>

where ${color} - is color you want

Note: piece has to be white (shades of gray). Sprite can be used too, just add add background-position as usual.

==== Accessing player avatar URLs ====

<pre>
getPlayerAvatar(playerId) {
let avatarURL = '';

if (null != $('avatar_' + playerId)) {
let smallAvatarURL = dojo.attr('avatar_' + playerId, 'src');
avatarURL = smallAvatarURL.replace('_32.', '_184.');
}
else {
avatarURL = 'https://x.boardgamearena.net/data/data/avatar/default_184.jpg';
}

return avatarURL;
},
</pre>

Note: This gets avatar URLs at 184x184 resolution. You can also use 92, 50, and 32 depending on which resolution you want.

==== Adding Image buttons ====

Its pretty trivial but just in case you need a working function:

ggg.js:
<pre>
addImageActionButton: function (id, div_html, handler) { // div_html is string not node
this.addActionButton(id, div_html, handler, '', false, 'gray');
dojo.style(id, "border", "none"); // remove ugly border
dojo.addClass(id, "bgaimagebutton"); // add css class to do more styling
return $(id); // return node for chaining
},

</pre>
Example of usage:
<pre>
this.addImageActionButton('button_coin',"<div class='coin'></div>", ()=>{ alert('Ha!'); });
</pre>

=== Other Fluff ===

==== Use thematic fonts ====

'''Ingredients:''' ggg.css

Sometime game elements use specific fonts of text, if you want to match it up you can load some specific font (IMPORTANT: from some '''free font''' source. See notes below).

[[File:Dragonline_font.png]]

.css
<pre>
/* latin-ext */
@font-face {
font-family: 'Qwigley';
font-style: normal;
font-weight: 400;
src: local('Qwigley'), local('Qwigley-Regular'), url(https://fonts.gstatic.com/s/qwigley/v6/2Dy1Unur1HJoklbsg4iPJ_Y6323mHUZFJMgTvxaG2iE.woff2) format('woff2');
unicode-range: U+0100-024F, U+1E00-1EFF, U+20A0-20AB, U+20AD-20CF, U+2C60-2C7F, U+A720-A7FF;
}
/* latin */
@font-face {
font-family: 'Qwigley';
font-style: normal;
font-weight: normal;
src: local('Qwigley'), local('Qwigley-Regular'), url(https://fonts.gstatic.com/s/qwigley/v6/gThgNuQB0o5ITpgpLi4Zpw.woff2) format('woff2');
unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02C6, U+02DA, U+02DC, U+2000-206F, U+2074, U+20AC, U+2212, U+2215, U+E0FF, U+EFFD, U+F000;
}
@font-face {
font-family: 'Qwigley';
font-style: normal;
font-weight: normal;
src: local('Qwigley'), local('Qwigley-Regular'), url(http://ff.static.1001fonts.net/q/w/qwigley.regular.ttf) format('ttf');
}

.zone_title {
display: inline-block;
position: absolute;
font: italic 32px/32px "Qwigley", cursive;
height: 32px;
width: auto;
}
</pre>

'''NB:''' if you need to include a font that's not available online, an extra action will be needed from an admin. Please include the font file(s) in your img directory, and mention it to admins when requesting your game to be moved to alpha. '''Please remember that the font has to be free, and include a .txt with all appropriate license information about the font.'''
You can look for free fonts (for example) on https://fonts.google.com or https://www.fontsquirrel.com/)

'''Content Security Policy'''

BGA runs a Content Security Policy which will limit the origins from which you can load external fonts, in order to prevent license abuse.

The CSP is a whitelist of allowed origins. To see the list, view the response headers of any page on Studio, and look for the "Content-Security-Policy" header.

You will specifically want to check for the font-src token within these headers, and limit any external fonts to these sources.

'''This list is subject to change''' but as of the time of writing, the only acceptabled external sites are use.typekit.net and fonts.gstatic.com.

=== Scale to fit for big boards ===

'''Ingredients:''' ggg_ggg.tpl, ggg.js

Lets say you have huge game board, and lets say you want it to be 1400px wide. Besides the board there will be side bar which is 240 and trim.
My display is 1920 wide so it fits, but there is big chance other people won't have that width. What do you do?

You have to decide:
* If board does not fit you want scale whole thing down, the best way is probably use viewport (see https://en.doc.boardgamearena.com/Your_game_mobile_version)
* You can leave the board as is and make sure it is scrollable horizonatally
* You add custom scale just for the board (can add user controls - and hook to transform: scale())

I tried to auto-scale but this just does work, too many variables - browser zoom, 3d mode, viewport, custom bga scaling, devicePixelRatio - all create some impossible coctail of zooming...
Here is scaling functing for custom user scaling

ggg_ggg.tpl:
<pre>
<div id="thething" class="thething">
... everything else you declare ...
</div>
</pre>

ggg.js:
<pre>
onZoomPlus: function() {
this.setZoom(this.zoom + 0.1);
},
onZoomMinus: function() {
this.setZoom(this.zoom - 0.1);
},

setZoom: function (zoom) {
zoom = parseInt(zoom) || 0;
if (zoom === 0 || zoom < 0.1 || zoom > 10) {
zoom = 1;
}
this.zoom = zoom;
var inner = document.getElementById("thething");

if (zoom == 1) {
inner.style.removeProperty("transform");
inner.style.removeProperty("width");
} else {
inner.style.transform = "scale(" + zoom + ")";
inner.style.transformOrigin = "0 0";
inner.style.width = 100 / zoom + "%";
}
localStorage.setItem(`${this.game_name}_zoom`, "" + this.zoom);
this.onScreenWidthChange();
},
</pre>

=== Dynamic tooltips ===

If you really need a dynamic tooltip you can use this technique. (Only use it if the static tooltips provided by the BGA framework are not sufficient.)

new dijit.Tooltip({
connectId: ["divItemId"],
getContent: function(matchedNode){
return "... calculated ...";
}
});

This is an out-of-the-box djit.Tooltip. It has a ''getContent'' method which is called dynamically.

The string returned by getContent() becomes the innerHTML of the tooltip, so it can be anything. In this example matchedNode is a dojo node representing dom object with id of "divItemId" but there are more parameters which I am not posting here which allows more sophisticated subnode queries (i.e. you can attach tooltip to all nodes with class or whatever).

[https://dojotoolkit.org/reference-guide/1.10/dijit/Tooltip.html dijit.Tooltip]

It's not part of the BGA API so use at your own risk.

=== Rendering text with players color and proper background ===

'''Ingredients:''' ggg.js

<pre>
/* Implementation of proper colored You with background in case of white or light colors */

divYou: function() {
var color = this.gamedatas.players[this.player_id].color;
var color_bg = "";
if (this.gamedatas.players[this.player_id] && this.gamedatas.players[this.player_id].color_back) {
color_bg = "background-color:#" + this.gamedatas.players[this.player_id].color_back + ";";
}
var you = "<span style=\"font-weight:bold;color:#" + color + ";" + color_bg + "\">" + __("lang_mainsite", "You") + "</span>";
return you;
},

/* Implementation of proper colored player name with background in case of white or light colors */

divColoredPlayer: function(player_id) {
var color = this.gamedatas.players[player_id].color;
var color_bg = "";
if (this.gamedatas.players[player_id] && this.gamedatas.players[player_id].color_back) {
color_bg = "background-color:#" + this.gamedatas.players[player_id].color_back + ";";
}
var div = "<span style=\"color:#" + color + ";" + color_bg + "\">" + this.gamedatas.players[player_id].name + "</span>";
return div;
},
</pre>

=== Cool realistic shadow effect with CSS ===

==== Rectangles and circles ====

It is often nice to have a drop shadow around tiles and tokens, to separate them from the table visually. It is very easy to add a shadow to rectangular elements, just add this to your css:

<pre>
.xxx-tile {
box-shadow: 3px 3px 3px #000000a0;
}
</pre>

box-shadow obeys '''border-radius''' of the element, so it will look good for rounded rectangles, and hence also circles (if border-radius is set appropriately).

box-shadow also supports various other parameters and can be used to achieve effects such as glowing, borders, inner shadows etc. If you need to animate a box-shadow, you may be able to get better performance (avoiding redraws) if you attach the shadow to another element (possibly an ::after pseudo-element) and change only the '''opacity''' of that element.

==== Irregular Shapes ====

If you wish to make a shadow effect for game pieces that are not a rectangle, but your game pieces are drawn from rectangles in a PNG image, you can apply the shadow to the piece using any art package and save it inside the image. This usually will yield the best performance. Remember to account for the size of the shadow when you lay out images in the sprite sheet.

However that sometimes will not be an option, for example if the image needs to be rotated while the shadow remains offset in the same direction. In this case, one option is to not use box-shadow but use filter, which is supported by recent major browsers. This way, you can use the alpha channel of your element to drop a shadow. This even work for transparent backgrounds, so that if you are using the "CSS-sprite" method, it will work!

For instance:

<pre>
.xxx-token {
filter: drop-shadow(0px 0px 1px #000000);
}
</pre>

Beware that some browsers still do not always draw drop-shadow correctly. In particular, Safari frequently leaves bits of shadow behind when objects move around the screen. In Chrome, shadows sometimes flicker badly if another element is animating close by. Some of these correctness issues can be solved by adding '''isolation: isolate; will-change: filter;''' to affected elements, but this significantly affects redraw performance.

Beware of performance issues - particularly on Safari (MacOS, iPhone and iPad). Keep in mind that drop-shadow are very GPU intensive. This becomes noticeable once you have about 40 components with drop-shadow filter. If that is your case, you can quite easily implement a user preference to disable shadows for users on slower machines:

gameoptions.inc.php
<pre>
100 => array(
'name' => totranslate('Shadows'),
'needReload' => true, // after user changes this preference game interface would auto-reload
'values' => array(
1 => array( 'name' => totranslate( 'Enabled' ), 'cssPref' => '' ),
2 => array( 'name' => totranslate( 'Disabled' ), 'cssPref' => 'no-shadow' )
)
),
</pre>

[game].css
<pre>
.no-shadow * {
filter: none !important;
}
</pre>For Safari, it is usually better to simply disable drop-shadow completely: [[Game interface stylesheet: yourgamename.css#Warning: using drop-shadow]].

==== Shadows with clip-path ====

For some reason, a shadow will not work together with clip-path on one element. To use both clip-path (when for example using .svg to cut out cardboard components from your .jpg spritesheet) and drop-shadow, you need to wrap the element into another one, and apply drop-shadow to the outer one, and clip-path to the inner one.

<pre>
<div class='my-token-wrap'>
<div class='my-token'>
</div>
</div>
</pre>
<pre>
.my-token-wrap {
filter: drop-shadow(0px 0px 1px #000000);
}
.my-token-wrap .my-token {
clip-path: url(#my-token-path);
}
</pre>

=== Using the CSS classes from the state machine ===

If you need to hide or show stuff depending on the state of your game, you can of course use javascript, but CSS is hand enough for that. The #overall-content element does change class depending on the game state. For instance, if you are in state ''playerTurn'', it will have the class ''gamestate_playerTurn''.

So now, if you want to show the discard pile only during player turns, you may use:

<pre>
#discard_pile { display: none }
.gamestate_playerTurn #discard_pile { display: block }
</pre>

This can be used if you want to change sizing of elements, position, layout or visual appearance.

== Game Model and Database design ==

=== Database for The euro game ===
Lets say we have a game with workers, dice, tokens, board, resources, money and vp. Workers and dice can be placed in various zones on the board, and you can get resources, money, tokens and vp in your home zone. Also tokens can be flipped or not flipped.

[[File:Madeira board.png]]

Now lets try to map it, we have
* (meeple,zone)
* (die, zone, sideup)
* (resource cube/money token/vp token,player home zone)
* (token, player home zone, flip state)
We can notice that resource and money are uncountable, and don't need to be track individually so we can replace our mapping to
* (resource type/money,player home zone, count)
And vp stored already for us in player table, so we can remove it from that list.

Now when we get to encode it we can see that everything can be encoded as (object,zone,state) form, where object and zone is string and state is integer. The resource mapping is slightly different semantically so you can go with two table, or counting using same table with state been used as count for resources.

So the piece mapping for non-grid based games can be in most case represented by (string: token_key, string: token_location, int: token_state), example of such database schema can be found here: [https://github.com/elaskavaia/bga-sharedcode/blob/master/dbmodel.sql dbmodel.sql] and class implementing access to it here [https://github.com/elaskavaia/bga-sharedcode/blob/master/modules/tokens.php table.game.php].

Variant 1: Minimalistic

CREATE TABLE IF NOT EXISTS `token` (
`token_key` varchar(32) NOT NULL,
`token_location` varchar(32) NOT NULL,
`token_state` int(10),
PRIMARY KEY (`token_key`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

{| class="wikitable"
|+token
! token_key
! token_location
! token_state
|-
|meeple_red_1
|home_red
|0
|-
|dice_black_2
|board_guard
|1
|-
|dice_green_1
|board_action_mayor
|3
|-
|bread
|home_red
|5
|}

Now how we represent resource counters such as bread?
Using same table from we simply add special counter token for bread and use state to indicate the count. Note to keep first column unique we have to add player identification for that counter, i.e. ff0000 is red player.

{| class="wikitable"
|+token
! token_key
! token_location
! token_state
|-
|bread_ff0000
|tableau_ff0000
|5
|}

See php module for this table here https://github.com/elaskavaia/bga-sharedcode/blob/master/modules/tokens.php

Variant 2: Additional resource table, resource count for each player id

CREATE TABLE IF NOT EXISTS `resource` (
`player_id` int(10) unsigned NOT NULL,
`resource_key` varchar(32) NOT NULL,
`resource_count` int(10) signed NOT NULL,
PRIMARY KEY (`player_id`,`resource_key`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

ALTER TABLE resource ADD CONSTRAINT fk_player_id FOREIGN KEY (player_id) REFERENCES player(player_id);

{| class="wikitable"
|+resource
! player_id
! resource_key
! resource_count
|-
|123456
|bread
|5
|}

Variant 3: More normalised

This version is similar to "card" table from hearts tutorial, you can also use exact cards database schema and Deck implementation for most purposes (even you not dealing with cards).

CREATE TABLE IF NOT EXISTS `token` (
`token_id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`token_type` varchar(16) NOT NULL,
`token_arg` int(11) NOT NULL,
`token_location` varchar(32) NOT NULL,
`token_state` int(10),
PRIMARY KEY (`token_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

{| class="wikitable"
|+token
! token_id
! token_type
! token_arg
! token_location
! token_state
|-
|22
|meeple
|123456
|home_123456
|0
|-
|23
|dice
|2
|board_guard
|1
|-
|26
|dice
|1
|board_action_mayor
|3
|-
|49
|bread
|0
|home_123456
|5
|}

Advantages of this would be is a bit more straightforward to do some queries in db, disadvantage its hard to read (as you can compare with previous example, you
cannot just look at say, ah I know what it means). Another questionable advantage is it allows you to do id randomisation, so it hard to do crafted queries to
cheat, the down side of that you cannot understand it either, and handcraft db states for debugging or testing.

=== Database for The card game ===

Lets say you have a standard card game, player have hidden cards in hand, you can draw card from draw deck, play card on tableau and discard to discard pile.
We have to design database for such game.

In real word to "save" the game we take a picture a play area, save cards from it, then put away draw deck, discard and hand of each player separately and mark it, also we will record current scoring (if any) and who's turn was it.

* Framework handles state machine transition, so you don't have to worry about database design for that (i.e. who's turn it is, what phase of the game we are at, you still have to design it but part of state machine step)
* Also framework supports basic player information, color, order around the table, basic scoring, etc, so you don't have to worry about it either
* The only thing you need in our database is state of the "board", which is "where each pieces is, and in what state", or (position,rotation) pair.

Lets see what we have for that:
* The card state is very simple, its usually "face up/face down", "tapped/untapped", "right side up/up side down"
* As position go we never need real coordinates x,y,z. We need to know what "zone" card was, and depending on the zone it may sometimes need an extra "z" or "x" as card order. The zone position usually static or irrelevant.
* So our model is: we have cards, which have some attributes, at any given point in time they belong to a "zone", and can also have order and state
* Now for mapping we should consider what information changes and what information is static, later is always candidate for material file
* For dynamic information we should try to reduce amount of fields we need
** we need at least a field for card, so its one
** we need to know what zone cards belong to, its 2
** and we have possibly few other fields, if you look closely at you game you may find out that most of the zone only need one attribute at a time, i.e. draw pile always have cards face down, hand always face up, also for hand and discard order does not matter at all (but for draw it does matter). So in majority of cases we can get away with one single extra integer field representing state or order
* In real database both card and zone will be integers as primary keys referring to additional tables, but in our case its total overkill, so they can be strings as easily

Variant 1: Minimalistic

<pre>
CREATE TABLE IF NOT EXISTS `card` (
`card_key` varchar(32) unsigned NOT NULL,
`card_location` varchar(32) NOT NULL,
`card_state` int(11) NOT NULL,
PRIMARY KEY (`card_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

Variant 2: More normalised

This version supported by Deck php class, so unless you want to rewrite db access layer go with this one

<pre>
CREATE TABLE IF NOT EXISTS `card` (
`card_id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`card_type` varchar(16) NOT NULL,
`card_type_arg` int(11) NOT NULL,
`card_location` varchar(16) NOT NULL,
`card_location_arg` int(11) NOT NULL,
PRIMARY KEY (`card_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

Note: if you using this schema, some zones/locations have special semantic. The 'hand' location is actually multiple locations - one per player, but player id is encoded as card_location_arg. If 'hand' in your game is ordered, visible or can have some other card states, you cannot use hand location (replacement is hand_<player_id> or hand_<color_id>)

== Code Organization ==

=== Including your own JavaScript module ===
'''Ingredients:''' ggg.js, modules/ggg_other.js

* Create ggg_other.js in modules/ folder and sync
<pre>
define([
"dojo", "dojo/_base/declare"
], function( dojo, declare )
{
return declare("bgagame.other", null, { // null here if we don't want to inherit from anything
constructor: function(){},
mystuff: function(){},
});

});

</pre>
* Modify ggg.js to include it

define([ "dojo", "dojo/_base/declare", "ebg/core/gamegui", "ebg/counter",
g_gamethemeurl + "modules/ggg_other.js" // load my own module!!!
], function(dojo,
declare) {

use it

foo = new bgagame.other();

=== Including your own JavaScript module (II) ===

* Create ggg_other.js in modules/ folder and sync

define([], function () {
return "value";
});

* Modify ggg.js to include it

define([
"dojo",
"dojo/_base/declare",
"bgagame/modules/ggg_other",
"ebg/core/gamegui",
"ebg/counter"
], function(dojo, declare, other) {

});

This is maybe a little bit more the idea of the AMD Loader than the first option, although the first option should work as well.

A little explanation to this:
The define function loads all the modules listed in the array and calls the following function with these loaded modules as parameters.
By putting your module at the third position in the array it is passed as the third parameter to the function. Be aware that the modules are resolved by position only, not by name. So you can load the module '''ggg_other''' and pass it as a parameter with the name '''other'''. '''gamegui''' and '''counter''' are passed in as well, but when the parameters are not defined they are just skipped. Because these modules put their content into the global scope it does not matter and you can use them from there.

In the example above the string "value" is passed for the parameter '''other''', but the function in your module can return whatever you want. It can be an object, an array, something you declared with dojo.declare, you can return even functions.
Your module can load other modules. Just put them in the array at the beginning and pass them as parameters to your function.
The advantage of passing the values as parameter is that you do not need to put these values in the global scope, so they can't be collisions with values defined in other scripts or the BGA Framework.

The dojo toolkit provides good documentation to all of its components, the complete documentation for the AMD-Loader is here:
https://dojotoolkit.org/documentation/tutorials/1.10/modules/index.html It should be still correct, even as it seems to be only for version 1.10

=== Including your own PHP module ===
'''Ingredients:''' ggg.game.php, modules/ggg_other.php

* Create ggg_other.php in modules/ folder and sync
* Modify ggg.game.php to include it

require_once ('modules/ggg_other.php');

=== Creating a test class to run PHP locally ===

'''Ingredients:''' ggg.game.php, stubs
For this you need stubs of other method you can use this for example
https://github.com/elaskavaia/bga-sharedcode/raw/master/misc/module/table/table.game.php

Create another php files, i.e ggg_test.php
<pre>
<?php
define("APP_GAMEMODULE_PATH", "misc/"); // include path to stubs, which defines "table.game.php" and other classes
require_once ('eminentdomaine.game.php');

class MyGameTest1 extends MyGame { // this is your game class defined in ggg.game.php
function __construct() {
parent::__construct();
include '../material.inc.php';// this is how this normally included, from constructor
}

// override/stub methods here that access db and stuff
function getGameStateValue($var) {
if ($var == 'round')
return 3;
return 0;
}
}
$x = new MyGameTest1(); // instantiate your class
$p = $x->getGameProgression(); // call one of the methods to test
if ($p != 50)
echo "Test1: FAILED";
else
echo "Test1: PASSED";

</pre>

Run from command line like
php7 ggg_test.php

If you do it this way - you can also use local php debugger (i.e. integrated with IDE or command line).

=== Avoiding code in dojo declare style ===
Dojo class declarations are rather bizzare and do not work with most IDEs.
If you want to write in plain JS with classes, you can stub all the dojo define/declare stuff
and hook your class into that, so the classes are outside of this mess.

NOTE: this technique is for experienced developers, do not try it if you do not understand
the consequences.

This is complete example of game .js class
<pre>
// Testla is game name is has to be changed
class Testla {
constructor(game) {
console.log('game constructor');
this.game = game;
this.varfoo = new MyFoo(); // this example of class from custom module
}

setup(gamedatas) {
console.log("Starting game setup", this.varfoo);
this.gamedatas = gamedatas;
this.dojo.create("div", { class: 'whiteblock', innerHTML: _("hello") }, 'thething');
console.log("Ending game setup");
};
onEnteringState(stateName, args) {
console.log('onEnteringState : ' + stateName, args);
this.game.addActionButton('b1',_('Click Me'), (e)=>this.onButtonClick(e));
};
onLeavingState(stateName) {
console.log('onLeavingState : ' + stateName, args);
};
onUpdateActionButtons(stateName, args) {
console.log('onUpdateActionButtons : ' + stateName, args);
};
onButtonClick(event) {
console.log('onButtonClick',event);
};
};

define([
"dojo", "dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
g_gamethemeurl + '/modules/foo.js' // custom module if needed
],
function(dojo, declare) {
// testla is game name is has to be changed
return declare("bgagame.testla", ebg.core.gamegui, {
constructor: function() {
this.xapp = new Testla(this);
this.xapp.dojo = dojo;
},
setup: function(gamedatas) {
this.xapp.setup(gamedatas);
},
onEnteringState: function(stateName, args) {
this.xapp.onEnteringState(stateName, args?.args);
},
onLeavingState: function(stateName) {
this.xapp.onLeavingState(stateName, args);
},
onUpdateActionButtons: function(stateName, args) {
this.xapp.onUpdateActionButtons(stateName, args);
},
});
});

</pre>

=== More readable JS: onEnteringState ===

If you have a lot of states in onEnteringState or onUpdateActionButtons and friends - it becomes rather wild, you can do this trick to call some methods dynamically.

<pre>

onEnteringState: function(stateName, args) {
console.log('Entering state: ' + stateName, args);

// Call appropriate method
var methodName = "onEnteringState_" + stateName;
if (this[methodName] !== undefined) {
console.log('Calling ' + methodName, args.args);
this[methodName](args.args);
}
},

onEnteringState_playerTurn: function(args) { // this is args directly, not args.args
// process
},

onEnteringState_playerSomethingElse: function(args) {
// process
},

</pre>

Note: since its ignores the undefined functions you don't have define function for each state, but on the other hand you cannot make typos.
Same applies to onUpdateActionButtons except you pass 'args' to method, not args.args, and for onLeavingState where you don't pass anything.

=== Frameworks and Preprocessors ===

* [[BGA Type Safe Template]] - Setting up a fully typed project using typescript and more!
* [[Using Vue]] - work-in-progress guide on using the modern framework Vue.js to create a game
* [[Using Typescript and Scss]] - How to auto-build Typescript and SCSS files to make your code cleaner

== Backend ==

=== Assigning Player Order ===
Normally when game starts there is "natural" player order assigned randomly.

If you want to deliberatly assign player order at the start of the game (for example, in a game with teams options), you can do so by retrieving the initialization-only player attribute '''player_table_order''' and using it to assign values to '''player_no''' (which is normally assigned at the start of a game in the order in which players come to the table). (See [https://en.doc.boardgamearena.com/Game_database_model:_dbmodel.sql#The_player_table Game database model] for more details.)

'''Example:'''
<pre>
// Retrieve inital player order ([0=>playerId1, 1=>playerId2, ...])
$playerInitialOrder = [];
foreach ($players as $playerId => $player) {
$playerInitialOrder[$player['player_table_order']] = $playerId;
}
ksort($playerInitialOrder);
$playerInitialOrder = array_flip(array_values($playerInitialOrder));

// Player order based on 'playerTeams' option
$playerOrder = [0, 1, 2, 3];
switch ($this->getGameStateValue('playerTeams')) {
case $this->TEAM_1_2:
$playerOrder = [0, 2, 1, 3];
break;
case $this->TEAM_1_4:
$playerOrder = [0, 1, 3, 2];
break;
case $this->TEAM_RANDOM:
shuffle($playerOrder);
break;
default:
case $this->TEAM_1_3:
// Default order
break;
}

// Create players
// Note: if you added some extra field on "player" table in the database (dbmodel.sql), you can initialize it there.
$sql =
'INSERT INTO player (player_id, player_color, player_canal, player_name, player_avatar, player_no) VALUES ';
$values = [];

foreach ($players as $playerId => $player) {
$color = array_shift($default_colors);
$values[] =
"('" .
$playerId .
"','$color','" .
$player['player_canal'] .
"','" .
addslashes($player['player_name']) .
"','" .
addslashes($player['player_avatar']) .
"','" .
$playerOrder[$playerInitialOrder[$playerId]] .
"')";
}
$sql .= implode(',', $values);
$this->DbQuery($sql);
$this->reattributeColorsBasedOnPreferences(
$players,
$gameinfos['player_colors']
);
$this->reloadPlayersBasicInfos();
</pre>

=== Send different notifications to active player vs everybody else ===

'''Ingredients:''' ggg.js

Hack alert. This is a hack. We were hoping for proper solution by bga framework.

This will allow you to send notification with two message one for specific player and one for everybody else including spectators.
Note that this does not split the data - all data must be shared.

Add this to .js file (if you already overriding it merge obviously)
<pre>
/** @Override */
format_string_recursive: function(log, args) {
if (typeof args.log_others != 'undefined' && typeof args.player_id != 'undefined' && this.player_id != args.player_id)
log = args.log_others;
return this.inherited(arguments); // you must call this to call super
},
</pre>

Example of usage (from eminentdomain)
<pre>
$this->notifyAllPlayers('tokenMoved',
clienttranslate('${player_name} adds +2 Colonies to ${place_name}'), // notification with show for player with player_id
['player_id'=>$player_id, // this is mandatory
'log_others'=>clienttranslate('${player_name} adds +2 Colonies to an unknown planet'), // notification will show for others
...
]);
</pre>

=== Send transient notifications without incrementing move ID ===

'''Ingredients:''' ggg.php

Hack alert. This is a hack.

Use this if you need to send some transient notification that should not create a new move ID. The notification should be idempotent -- it should have no practical effect on the game state and would be '''safe to drop''' (e.g., it would not matter if a player never received this notification). For example, in a co-op game you want all players to see a real-time preview of some action, before the active player commits their turn.

Doing this mainly affects the instant replay & archive modes. During replay, the BGA framework automatically inserts a 1.5-second pause between each "move". With this hack, your transient notifications are not considered to be a "move", so no pause gets added.

; In ggg.php
<pre>
$this->not_a_move_notification = true; // note: do not increase the move counter
$this->notifyAllPlayers('cardsPreview', '', $args);
</pre>

Note: you cannot have code that send notification or even changes state after this, and you cannot reset this variable back either because it only takes effect when you exit action handling function

== Assorted Stuff ==

=== Out-of-turn actions: Un-pass ===

'''Ingredients:''' ggg.js, ggg.game.php, ggg.action.php, states.inc.php

In multiplayer game sometimes players passes but than they think more and want to un-Pass and redo their choice.
To re-active a player who passes some trickery required.

Define a special action that does that and hook it up.

In states.inc.php add an action to mmultipleactiveplayer state to "unpass", lets call it "actionCancel"

In ggg.action.php add action hook
public function actionCancel() {
$this->setAjaxMode();
$this->game->actionCancel();
$this->ajaxResponse();
}

In ggg.game.php add action handler
function actionCancel() {
$this->gamestate->checkPossibleAction('actionCancel');
$this->gamestate->setPlayersMultiactive(array ($this->getCurrentPlayerId() ), 'error', false);
}

Finally to call this in client ggg.js you would do something like:
<pre>
onUpdateActionButtons: function(stateName, args) {
if (this.isCurrentPlayerActive()) {
// ...
} else if (!this.isSpectator) { // player is NOT active but not spectator
switch (stateName) {
case 'playerTurnMultiPlayerState':
this.addActionButton('button_unpass', _('Oh no!'), 'onUnpass');
break;
}
}
}

onUnpass: function(e) {
this.bgaPerformAction("actionCancel", null, { checkAction: false }); // no checkAction!
}
</pre>
Although be careful that if the turn comes back to the player while he is about to click cancel, the action buttons will be updated and the player will misclick which can be quite frustrating. To avoid this, move the cancel button to another position, like to the left of pagemaintitletext:
dojo.place('button_unpass', 'pagemaintitletext', 'before');
Being out of the generalactions div, it won't be automatically destroyed like normal buttons, so you'll have to handle that yourself in onLeavingState. You might also want to change the button color to red (blue buttons for active player only, red buttons also for inactive players?)

Note: same technique can be used to do other out-of-turn actions, such as re-arranging cards in hand, exchanging resources, etc (i.e. if permitted by rules, such as "at any time player can...")

=== Multi Step Interactions: Select Worker/Place Worker - Using Selection ===

'''Ingredients:''' ggg.js

Simple way to implement something like that without extra states is to use "selection" mechanism. When user click on worker add some sort of class into that element i.e. 'selected' (which also have to have some indication by css i.e. outline).

Than user can click on placement zone, you can use dojo.query for "selected" element and use it along with zone id to send data to server. If proper worker is not selected yet can give a error message using this.showMessage(...) function.

Extra code required to properly cleanup selection between states.
Also when you do that sometimes you want to change the state prompt, see below 'Change state prompt'

=== Multi Step Interactions: Select Worker/Place Worker - Using Client States ===

'''Ingredients:''' ggg.js

I don't think its documented feature but there is a way to do client-only states, which is absolutely wonderful for few reasons
* When player interaction is two step process, such as select worker, place worker, or place worker, pick one of two resources of your choice
* When multi-step process can result of impossible situation and has to be undone (by rules)
* When multi-step process is triggered from multiple states (such as you can do same thing as activated card action, pass action or main action)

So lets do Select Worker/Place Worker

Define your server state as usual, i.e. playerMainTurn -> "You must pick up a worker".
Now define a client state, we only need "name" and "descriptionmyturn", lets say "client_playerPicksLocation". Always prefix names of client state with "client_" to avoid confusion. Now we have to do the following:
* Have a handler for onUpdateActionButtons for playerMainTurn to activate all possible workers he can pick
* When player clicks workers, remember the worker in one of the members of the main class, I usually use one called this.clientStateArgs.
* Transition to new client state
onWorker: function(e) {
var id = event.currentTarget.id;
dojo.stopEvent(event);
... // do validity checks
this.clientStateArgs.worker_id = id;
this.setClientState("client_playerPicksLocation", {
descriptionmyturn : _("${you} must select location"),
});
}
* Have a handler for onUpdateActionButtons for client_playerPicksLocation to activate all possible locations this worker can go AND add Cancel button (see below)
* Have a location handler which will eventually send a server request, using stored this.clientStateArgs.worker_id as worker id
* The cancel button should call a method to restore server state, also if you doing it for more than one state you can add this universally using this.on_client_state check

if (this.isCurrentPlayerActive()) {
if (this.on_client_state && !$('button_cancel')) {
this.addActionButton('button_cancel', _('Cancel'), dojo.hitch(this, function() {
this.restoreServerGameState();
}));
}
}
Note: usually I call my own function call this.cancelLocalStateEffects() which will do more stuff first then call restoreServerGameState(), same function is usually needs to be called when server request has failed (i.e. invalid move)

Note: If you need more than 2 steps, you may have to do client side animation to reflect the new state, which gets trickier because you have to undo that also on cancellation.

Code is available here [https://github.com/elaskavaia/bga-sharedcode/blob/master/sharedcode.js sharedcode.js] (its using playerTurnPlayCubes and client_selectCubeLocation).

=== Action Stack - Using Client States ===

Action stack required where game is very complex and use triggered effects that can "stack". It not always actual stack, it can be queue or random access
Examples:
* Magic the Gathering - classic card game where effects go on Stack, that allows to counter spell and counter spell of counter spell (not on bga - it just example of mechanics)
* Ultimate Railroads - action taking game where effects can be executed in any order
* Lewis and Clark - card game where actions executed as queue

There is two ways of implementing it - on the server or the client.
For the server see article below.
The requirement for client side stack implementation is - all action can be undone, which means
* No dice rolls
* No card drawn
* No other players interaction

No snippets are here, as this will be too complex but basically flow is:
* You have a action/effect stack (queue/list) as js object attached to "this", i.e. this.unprocessed_actions
* When player plays a card, worker, etc, you read the effect of that card from the material file (client copy), and place into stack
* Then we call dispatch method which pulls the next action from the stack and change client state accordinly, i.e. this.setClientState("client_playerGainsCubes")
* When players acts on it - the action is removed from the stack and added to "server action arguments" list, this is another object which be used to send ajax call, i.e. this.clientStateArgs
* If nothing left in stack we can submit the ajax call assembling parameters from collected arguments (that can include action name)
* This method allows cheap undo - by restoring server state you will wipe out all user actions (but if you need intermediate aninmation you have to handle it yourself)

Code can be found in Ultimate Railroads game (but it is random access list - so it a bit complex) and Lewis and Clark (complexity - user can always deny part of any effect)

=== Action Stack - Using Server States ===

See definition of Action Stack above.

To implement you usually need another db table that has the following fields: index of effect - which is used for sorted access, type - which is essense of the effect (i.e. collect resource), some extra arguments (i.e. resource type and resource count), and usually owner of the effect (i.e. player id)
The flow is:
* There is some initial player state, where player can play card for example
* Player main action - pushes the card effect on stack, which also can cause triggered effects which also go on stack
* After action processing is finished switch to game state which is "dispatcher"
* Dispatcher pulls the top effect (whatever definition of the top is), changes the active player and changes the state to appropriate player state to collect response. The "top" can be choice of multiple actions, in this case player has to chose one before resolving the effect.
* Player state knows about the stack and pulls arguments (argX) from the effect arguments of the db
* Player action should clear up the top effect, and can possibly add more effects, then switch to "dispatcher" state again
* If stack is empty, dispatcher can either pick next player itself or use another game state which responsible for picking next player

Code can be found in Tapestry and Terraforming Mars.
=== Custom error/exception handling in JavaScript ===

; In ggg.php
Throw BgaUserException with some easy-to-identify prefix such as "!!!" and a custom error code. DO NOT TRANSLATE this message text. The exception will rollback database transaction and cancel all changes (including any notifications).
<pre>
function foo(bool $didConfirm = false): void
{
// do processing for the user's move
// afterwards, you determine this move will end the game
// so you want to rollback the transaction and require the user to confirm the move first

if ($gameIsEnding && !$didConfirm) {
throw new BgaUserException('!!!endGameConfirm', 9001);
}
}
</pre>

; In ggg.js
Override framework function showMessage to suppress the red banner message and gamelog message when you detect the "!!!" prefix
<pre>
/* @Override */
showMessage: function (msg, type) {
if (type == "error" && msg && msg.startsWith("!!!")) {
return; // suppress red banner and gamelog message
}
this.inherited(arguments);
},
</pre>

Deal with the error in your callback:
<pre>
fooAction: function (didConfirm) {
var data = {
foo: "bar",
didConfirm: !!didConfirm,
};
this.bgaPerformAction("fooAction", data).catch((error, errorMsg) => {
if (error && errorMsg == "!!!endGameConfirm") {
// your custom error handling goes here
// for example, show a confirmation dialog and repeat the action with additional param
this.confirmationDialog(
_("Doing the foo action now will end the game"),
() => this.fooAction(true)
);
}
});
},
</pre>

For custom global error handling, you could modify ajaxcallwrapper:
<pre>
ajaxcallwrapper: function (action, args, handler) {
if (!args) args = {};
args.lock = true;
args.version = this.gamedatas.version;
if (this.checkAction(action)) {
this.bgaPerformAction(
action,
args
).catch((error, errorMsg, errorCode) => {
if (error && errorMsg == "!!!checkVersion") {
this.infoDialog(
_("A new version of this game is now available"),
_("Reload Required"),
() => {
window.location.reload();
},
true
);
} else {
if (handler) handler(error, errorMsg, errorCode);
}
}
);
}
},
</pre>

=== Force players to refresh after new deploy ===

When you deploy a new version of your game, the PHP backend code is immediately updated but the JavaScript/HTML/CSS frontend code *does not update* for active players until they manually refresh the page (F5) in their browser. Obviously this is not ideal. In the best case, real-time tables don't see your shiny new enhancements. In the worst case, your old JS code isn't compatible with your new PHP code and the game breaks in strange ways (any bug reports filed will be false positives and unable to reproduce). To avoid any problems, you should force all players to immediately reload the page following a new deploy.

By throwing a "visible" exception (simplest solution), you'll get something like this which instructs the user to reload:

[[File:Force-refresh.png|950x950px]]

Or, if you combine this technique with the above custom error handling technique, you could do something a bit nicer. You could show a dialog box and automatically refresh the page when the user clicks "OK":

[[File:Reload-required.png|500x500px]]
; In ggg.php
Transmit the server version number in <code>getAllDatas()</code>.
<pre>
protected function getAllDatas(): array
{
$players = $this->getCollectionFromDb("SELECT player_id id, player_score score FROM player");
return [
'players' => $players,
'version' => intval($this->gamestate->table_globals[300]), // <-- ADD HERE
...
];
}
</pre>

Create a helper function to fail if the client and server versions mismatch. Note the version check uses <code>!=</code> instead of <code><</code> so it can support rollback to a previous deploy as well. ;-)
<pre>
public function checkVersion(int $clientVersion): void
{
if ($clientVersion != intval($this->gamestate->table_globals[300])) {
// Simplest way is to throw a "visible" exception
// It's ugly but comes with a "click here" link to refresh
throw new BgaVisibleSystemException($this->_("A new version of this game is now available. Please reload the page (F5)."));

// For something prettier, throw a "user" exception and handle in JS
// (see BGA cookbook section above on custom error handling)
throw new BgaUserException('!!!checkVersion');
}
}
</pre>
; In ggg.action.php
Create a helper function for actions:
<pre>
private function checkVersion()
{
$clientVersion = (int) $this->getArg('version', AT_int, false);
$this->game->checkVersion($clientVersion);
}
</pre>

Call <code>$this->checkVersion()</code> at the top of <b>every action function</b>, immediately after <code>$this->setAjaxMode()</code>:
<pre>
public function move()
{
$this->setAjaxMode();
$this->checkVersion(); // <-- ADD HERE
...
$this->ajaxResponse();
}
</pre>

; In ggg.js
Transmit the version (from gamedatas) as a parameter with every ajax call. For example, if you're already using a wrapper function for every ajax call, add it like this:
<pre>
ajaxcallwrapper: function (action, args) {
if (!args) args = {};
args.version = this.gamedatas.version; // <-- ADD HERE
this.bgaPerformAction(action, args);
},
</pre>

=== Disable / lock table creation for new deploy ===

If you are deploying a major new game version, especially if it involves upgrading production game databases, you may have a lot of angry players if you break their tables. Depending on your changes, you may be able to restore the previous version and fix the tables easily.

However, if a new deploy turns out bad and players created turn-based tables while it was live, it may be quite difficult to fix those tables, since they were created from a bad deploy.

The solution? You can announce in your game group that you are locking table creation, and then in your new version, add an impossible startcondition to an existing option.
Note: This only makes sense if you have a few games running in real time mode in the time of deployment, otherwise it won't achieve much, unless you wait at least a day for other turn based games to break (or not)

Here is an example of an option with only 2 values (if you don't have options at all you have to create a fake option to use this method, if you have more values - you have to list them all):

; In gameoptions.json
<pre>
"startcondition": {
"0": [ { "type": "minplayers", "value": 32, "message": "Maintenance in progress. Table creation is disabled." } ],
"1": [ { "type": "minplayers", "value": 32, "message": "Maintenance in progress. Table creation is disabled." } ]
},
</pre>
; In gameoptions.inc.php (older method if you have it in php)
<pre>
// TODO NEXT remove after testing deploy to upgrade, here 0 and 1 - replace with values of your option!
'startcondition' => [
0 => [ [ 'type' => 'minplayers', 'value' => 32, 'message' => totranslate('Maintenance in progress. Table creation is disabled.') ] ],
1 => [ [ 'type' => 'minplayers', 'value' => 32, 'message' => totranslate('Maintenance in progress. Table creation is disabled.') ] ],
],
</pre>

* Be sure to click "Reload game options configuration" after making this change, then test in studio (test that you cannot create any table)
* Deploy to production
* Now, when a player attempts to create a new table, they will see a red error bar with your "Maintenance in progress" message.
* Wait for screaming (if you have real times games in progress waiting 15 min probably ok, if you have only turn based games, probably a day)
* Once you confirm the new deploy looks good, you can revert the change in gameoptions.inc.php and do another deploy.

=== Local Storage ===

There is not much you can store in localStorage (https://developer.mozilla.org/docs/Web/API/Window/localStorage), since most stuff should be stored either in game db or in user prefrences,
but some stuff makes sense to store there, for example "zoom" level (if you use custom zooming). This setting really affect this specific host and specific browser, setting it localStorage makes most sense.

game.js
<pre>
setup: function (gamedatas) {
let zoom = localStorage.getItem(`${this.game_name}_zoom`);
this.setZoom(zoom);
...
},
</pre>
In this case setZoom is custom function to actually set it.
When zoom changed, for example when some buttons pressed, store current value (but sanitize it so it never so bad that game cannot be viewed

<pre>
setZoom: function (zoom) {
zoom = parseInt(zoom) || 0;
if (zoom === 0 || zoom < 0.1 || zoom > 10) {
zoom = 1;
}
this.zoom = zoom;
localStorage.setItem(`${this.game_name}_zoom`, "" + this.zoom);
... do actual zooming stuff
},
</pre>

=== Capture client JavaScript errors in the "unexpected error" log ===

PHP (backend) errors are recorded in the "unexpected error" log, but JavaScript (frontend) errors are only available in the browser itself. This means you have no visibility about things that go wrong in the client... unless you make clients report their errors to the server.

; In actions.php:
<pre>
public function jsError()
{
$this->setAjaxMode(false);
$this->game->jsError($_POST['userAgent'], $_POST['msg']);
$this->ajaxResponse();
}
</pre>

; In game.php:
<pre>
public function jsError($userAgent, $msg): void
{
$this->error("JavaScript error from User-Agent: $userAgent\n$msg // ");
}
</pre>

; In game.js:
<pre>
define(["dojo", "dojo/_base/declare", "ebg/core/gamegui", "ebg/counter"], function (dojo, declare) {
const uniqJsError = {};
...

return declare("bgagame.nowboarding", ebg.core.gamegui, {
...
/* @Override */
onScriptError(msg) {
if (!uniqJsError[msg]) {
uniqJsError[msg] = true;
console.error("⛔ Reporting JavaScript error", msg);
this.ajaxcall(
"/" + this.game_name + "/" + this.game_name + "/jsError.html",
{
msg,
userAgent: navigator.userAgent,
},
this,
() => {},
() => {},
"post"
);
}
this.inherited(arguments);
},
</pre>

== Algorithms ==

=== Generate permutations in lexicographic order ===

Use this when you have an array like [1, 2, 3, 4] and need to loop over some/all 24 permutations of possible ordering. This type of [https://www.php.net/manual/en/language.generators.syntax.php generator function] computes each possibility one at a time, making it vastly more efficient than either a normal iteration or recursive function that produce all possibilities up front.

<pre>
function generatePermutations(array $array): Generator
{
// https://en.wikipedia.org/wiki/Permutation#Generation_in_lexicographic_order
// Sort the array and this is the first permutation
sort($array);
yield $array;

$count = count($array);
do {
// Find the largest index k where a[k] < a[k + 1]
// End when no such index exists
$found = false;
for ($k = $count - 2; $k >= 0; $k--) {
$kvalue = $array[$k];
$knext = $array[$k + 1];
if ($kvalue < $knext) {
// Find the largest index l greater than k where a[k] < a[l]
for ($l = $count - 1; $l > $k; $l--) {
$lvalue = $array[$l];
if ($kvalue < $lvalue) {
// Swap a[k] and a[l]
[$array[$k], $array[$l]] = [$array[$l], $array[$k]];

// Reverse the sequence from a[k + 1] up to and including the final element
$reverse = array_reverse(array_slice($array, $k + 1));
array_splice($array, $k + 1, $count, $reverse);
yield $array;

// Restart with the new array to find the next permutation
$found = true;
break 2;
}
}
}
}
} while ($found);
}
</pre>

Usage:
<pre>
$cash = [4, 1, 2, 3, 4];
foreach ($this->generatePermutations($cash) as $p) {
// your code here to evaluate permutation $p
// first iteration: $p = [1, 2, 3, 4, 4]
// last (60th) iteration: $p = [4, 4, 3, 2, 1]
// break from loop once you achieve your goal
}
</pre>

[[Category:Studio]]

Game interface logic: Game.js

2024-09-23T10:01:59Z

Sguzzer Gunayer: /* Classes */

{{Studio_Framework_Navigation}}

__TOC__

This is the main file for your game interface. Here you will define:

* Which actions on the page will generate calls to the server.
* What happens when you get a notification for a change from the server and how it will show in the browser.
* Setup user interface

== File structure ==

The details of how the file is structured are described below with comments in the code skeleton provided to you.

Here is the basic structure:

* '''constructor''': here you can define global variables for your whole interface.
* '''setup''': this method is called when the page is refreshed, and sets up the game interface.
* '''onEnteringState''': this method is called when entering a new game state. You can use it to customize the view for each game state.
* '''onLeavingState''': this method is called when leaving a game state.
* '''onUpdateActionButtons''': called on state changes, in order to add action buttons to the status bar. Note: in a multipleactiveplayer state, it will be called when another player has become inactive.
* ''(utility methods)'': this is where you can define your utility methods.
* ''(player's actions)'': this is where you can write your handlers for player actions on the interface (example: click on an item).
* '''setupNotifications''': this method associates notifications with notification handlers. For each game notification, you can trigger a javascript method to handle it and update the game interface.
* ''(notification handlers)'': this is where you define the notifications handlers associated with notifications in '''setupNotifications''', above.

More details:

'''setup(gamedatas: object) '''
This method must set up the game user interface according to current game situation specified in parameters.
The method is called each time the game interface is displayed to a player, ie:

* when the game starts
* when a player opens a game in the browser later
* when a player refreshes the game page (F5)
* when player does a server side Undo

"gamedatas" argument contains all data retrieved by your "getAllDatas" PHP method and some more.

'''onEnteringState(stateName: string, args: { args: any } | null): void'''

This method is called each time we enter a new game state.
You can use this method to perform some user interface changes at this moment.
To access state arguments passed via calling php arg* method use args?.args.
Typically you would do something only for active player, using this.isCurrentPlayerActive() check.
It is also called (for the current game state only) when doing a browser refresh (after the setup method is called).

'''Warning''': for multipleactiveplayer states:
the active players are NOT active yet so you must use onUpdateActionButtons to perform the client side operation which depends on a player active/inactive status.
If you are doing initialization of some structures which do not depend on the active player, you can just replace (this.isCurrentPlayerActive()) with (!this.isSpectator)
for the main switch in that method.

See more details in [[Your_game_state_machine:_states.inc.php#Difference_between_Single_active_and_Multi_active_states]]

'''onLeavingState(stateName: string): void'''

This method is called each time we leave a game state.
You can use this method to perform some user interface changes at this point (i.e. cleanup).

'''onUpdateActionButtons(stateName: string, args: object | null): void'''

In this method you can manage "action buttons" that are displayed in the action status bar and highlight active UI elements.
To access state arguments passed via calling php arg* method use '''args''' parameter. Note: args can be null! For '''game''' states and when you don't supply state args function - it is null.
This method is called when the active or multiactive player changes. In a classic "activePlayer" state this method is called before the onEnteringState state.
In multipleactiveplayer state it is a mess. The sequencing of calls depends on whether you get into that state from transitions OR from reloading the whole game (i.e. F5).

See more details in [[Your_game_state_machine:_states.inc.php#Difference_between_Single_active_and_Multi_active_states]]

== Dojo framework ==

BGA uses the [http://dojotoolkit.org/ Dojo Javascript framework].

The Dojo framework allows us to do complex things more easily. The BGA framework uses Dojo extensively.

To implement a game, you only need to use a few parts of the Dojo framework. All the Dojo methods you need are described on this page.

== Javascript minimization (after July 2020) ==

For performance reasons, when deploying a game the javascript code is minimized using '''terser''' (https://github.com/terser/terser). This minifier works with modern javascript syntax. From your project "Manage game" page, you can now test a minified version of your javascript on the studio (and revert to the original).

NB: it has been reported that there is an issue with this minifier and percentage values for opacity.

== Accessing Players Information ==

'''this.player_id: number'''
id of the player who is looking at the game. The player may not be part of the game (i.e. spectator)
if (notif.args.player_id == this.player_id) {
...
}

'''this.isSpectator: boolean'''
Flag set to true if the user at the table is a spectator (not a player).

Example:
<pre>
if (this.isSpectator) {
this.player_color = 'ffffff';
} else {
this.player_color = gamedatas.players[this.player_id].color;
}
</pre>

Note: If you want to hide an element from spectators, you should use [[Game_interface_stylesheet:_yourgamename.css#spectatorMode|CSS 'spectatorMode' class]].

You may consider making a function like this, to detect if the game is in a read-only state (i.e. non-interactive):
// Returns true for spectators, instant replay (during game), archive mode (after game end)
isReadOnly: function () {
return this.isSpectator || typeof g_replayFrom != 'undefined' || g_archive_mode;
}

'''this.gamedatas: object'''
Contains the initial set of data to init the game, created at game start or by game refresh (F5).
You can update it as needed to keep an up-to-date reference of the game on the client side if you need it, however most of the time this is unnecessary.

Note: In hotseat mode, the framework does not keep this.gamedatas of hotseat players and shares the same set as the main player to store data.

Note: be careful when you update this data structurally, many framework functions expect data to be certain way and they will break if they see something else.

Typical example of accessing player's info
<pre>
for (var player_id in this.gamedatas.players) {
var playerInfo = this.gamedatas.players [player_id];
var c = playerInfo.color;
var name = playerInfo.name;
// do something
}
</pre>

'''this.isCurrentPlayerActive(): boolean'''
Returns true if the player on whose browser the code is running is currently active (it's his turn to play). Note: see remarks above about usage of this function inside onEnteringState method.
if (this.isCurrentPlayerActive()) {

'''this.getActivePlayerId(): number'''
Return the ID of the active player, or null if we are not in an "activeplayer" type state.
if (this.player_id == this.getActivePlayerId()) ...

'''this.getActivePlayers(): number[]'''
Return an array with the IDs of players who are currently active (or an empty array if there are none).

== Accessing and manipulating the DOM ==

=== Element by Id ===

'''$(elementId: ElementOrId)'''

The $ function is used to get an HTML element using its "id" attribute.

Example: modify the content of a "span" element:

<pre>
In your HTML code:
<span id="a_value_in_the_game_interface">1234</span>

In your Javascript code:
$('a_value_in_the_game_interface').innerHTML = "9999";
</pre>

Note: It is safe to use if you don't know if variable is string (id of element) or element itself, i.e.
<pre>
foo: function(card) {
card = $(card); // now its node, no need to write if (typeof card === 'string') ...
// but its good idea to check for null here
...
}
</pre>

'''getElementById(elementId: string)'''

Note: $() is the standard method to access some HTML element with the BGA Framework. You can use '''getElementById''' but a longer to type and less handy as it does not do some checks.

=== Style ===

'''dojo.style(node: ElementOrId, styleName: string, styleValue: any): void'''

With dojo.style you can modify the CSS property of any HTML element in your interface.

Examples:

<pre>
// Make an element disappear
dojo.style( 'my_element', 'display', 'none' );

// Give an element a 2px border
dojo.style( 'my_element', 'borderWidth', '2px' );

// Change the background position of an element
// (very practical when you are using CSS sprites to transform an element to another)
dojo.style( 'my_element', 'backgroundPosition', '-20px -50px' );
</pre>

Note: if you have to modify several CSS properties of an element, or if you have a complex CSS transformation to do, you should consider using dojo.addClass/dojo.removeClass (see below).

You can also use object to set multiple values
<pre>
dojo.setStyle("thinger", {
"opacity": 0.5,
"border": "3px solid black",
"height": "300px"
});
</pre>

'''this.addStyleToClass(cssClassName: string, styleName: string, styleValue: any):''' '''void'''

Same as dojo.style(), but for all the nodes set with the specified cssClassName
Equivalent of

dojo.query(`.${aclass}`).style(styleName, styleValue)

<pre>
dojo.query("#baz > div").style({
opacity:0.75,
fontSize:"13pt"
});
</pre>

'''Vanilla JS style'''
$('my_element').style.display='none'; // set
var display = $('my_element').style.display; // get
$('my_element').style.removeProperty('display'); // remove

=== Classes ===

'''dojo.addClass(node: ElementOrId, classes: string): void'''

'''dojo.removeClass(node: ElementOrId, classes: string): void'''

'''dojo.hasClass(node: ElementOrId, aclass: string): void'''

'''dojo.toggleClass(node: ElementOrId, aclass: string): void'''

In many situations, many small CSS property updates can be replaced by a CSS class change (i.e., you add a CSS class to your element instead of applying all modifications manually).

Advantages are:
* All your CSS stuff remains in your CSS file.
* You can add/remove a list of CSS modifications with a simple function and without error.
* You can test whether you applied the CSS to an element with the '''dojo.hasClass''' method.

Example from ''Reversi'':

<pre>
// We add "possibleMove" to an element
dojo.addClass( 'square_'+x+'_'+y, 'possibleMove' );

// In our CSS file, the class is defined as:
.possibleMove {
background-color: white;
opacity: 0.2;
filter:alpha(opacity=20); /* For IE8 and earlier */
cursor: pointer;
}

// So we've applied 4 CSS property changes in one line of code.

// ... and when we need to check if a square is a possible move on the client side:
if( dojo.hasClass( 'square_'+x+'_'+y, 'possibleMove' ) )
{ ... }

// ... and if we want to remove all possible moves in one line of code (see "dojo.query" method):
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );
</pre>

'''Vanilla JS classList'''

This is the only exception where dojo versions are better
// add class
$(token_id).classList.addClass('possibleMove');
// remove class
$(token_id).classList.removeClass('possibleMove');
// add 2 classes
const myclasses = ['a','b'];
$(token_id).classList.addClass(...myclasses);
// add classes to query result
document.querySelectorAll(".hand .card").forEach((node)=>node.classList.addClass('possibleMove'));

=== Attributes ===

;dojo.attr

With dojo.attr you can access or change the value of an attribute or property of any HTML element in your interface.

Exemple:
<pre>
// Get the title of a node
var title = dojo.attr( id, 'title' );
// Change the height of a node
dojo.attr( 'img_growing_tree', 'height', 100 );
</pre>

'''Vanilla JS attr'''

$(token).id=new_id; // set attr for "id"
var id = $(token).id; // get

=== Queries ===

'''dojo.query(cssSelector: string): Element[]'''

With dojo.query, you can query a bunch of HTML elements with a single function, with a "CSS selector" style.

Example:
<pre>
// All elements with class "possibleMove":
var elements = dojo.query( '.possibleMove' );

// Count number of tokens (i.e., elements of class "token") on the board (i.e., the element with id "board"):
dojo.query( '#board .token' ).length;
</pre>

But what is really cool with dojo.query is that you can combine it with almost all methods above.

Examples:
<pre>
// Trigger a method when the mouse enter in any element with class "meeple":
dojo.query( '.meeple' ).connect( 'onmouseenter', this, 'myMethodToTrigger' );

// Hide all meeples who are on the board
dojo.query( '#board .meeple' ).style( 'display', 'none' );
</pre>

'''Vanilla JS query'''

var cards=document.querySelectorAll(".hand .card");// all cards in all hands
var cards=$('hand').querySelectorAll(".card");// all cards in specific hand
var card=document.querySelector(".hand .card");// first card or null if none (super handy)

=== Creating and Destroying elements ===

'''dojo.empty(node: ElementOrId)'''

Remove all children of the node element
dojo.empty('my_hand');

'''dojo.destroy(node: ElementOrId)'''

Remove the element
dojo.destroy('my_token');

dojo.query(".green", mynode).forEach(dojo.destroy); // this remove all subnode of class green from mynode

'''dojo.create(tag: string, attributes?: obj, parent?: ElementOrId): Element'''

Create element

dojo.create("div", { class: "yellow_arrow" }, parent); // this creates div with class yellow_array and places it in "parent"

'''this.format_block(name: string, args: object): string'''
This bga function that takes global var from template file and substitute variables, typical use would be

var player = gamedatas.players[player_id];
var div = this.format_block('jstpl_player_board', player ); // var jstpl_player_board = ... is defined in .tpl file
Note: result is trimmed

'''this.format_string(name: string, args: object): string'''
This bga function just substitute variables in a string, i.e.
<pre>
var div = this.format_string('<div color="${player_color}"></div>', {player_color: '#ff0000'} );
</pre>
Note: result is trimmed

Note: this can be replaced by using backquoted string now:
const player_color = '#ff0000';
const div = `<div color="${player_color}"></div>`;

'''this.format_string_recursive'''
This bga function is similar to this.format_string but is capable of processing recursive argument structures and translations. It is used to format server notifications.

TODO: find better place for these function docs

=== Moving elements ===

'''dojo.place(node: string | Element, refNode: ElementOrId, pos?: string | number): Element'''

dojo.place is the best function to insert HTML code somewhere in your game interface without breaking something. It is much better to use than the '''innerHTML=''' method if you must insert HTML tags and not only values.

node:

Can be a String or a DOM node. If it is a string starting with “<”, it is assumed to be an HTML fragment, which will be created. Otherwise it is assumed to be an id of a DOM node.

<pre>
// Insert your HTML code as a child of a container element
dojo.place( "<div class='foo'></div>", "your_container_element_id" );
</pre>

pos:

Optional argument. Can be a number or one of the following strings: “before”, “after”, “replace”, “only”, “first”, or “last”. If omitted, “last” is assumed.

"replace": Replace the container element with my_node element

"first": Places the node as a child of the reference node. The node is placed as the first child.

"last" (default): Places the node as a child of the reference node. The node is placed as the last child.

"before": places the node right before the reference node.

"after": places the node right after the reference node.

"only": replaces all children of the reference node with the node.

positive integer: This parameter can be a positive integer. In this case, the node will be placed as a child of the reference node with this number (counting from 0). If the number is more than number of children, the node will be appended to the reference node making it the last child.

<pre>
// Replace all children of container with my_node
dojo.place( $('my_node'), "your_container_element_id", "only" );
</pre>

See also full doc on dojo.place: [https://dojotoolkit.org/reference-guide/1.7/dojo/place.html]

Usually, when you want to insert some piece of HTML in your game interface, you should use "[[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl#Javascript_templates|Javascript templates]]".

But you can also relocate elements like that. Note: it won't animate if you do that.

'''this.placeOnObject(mobile_obj: ElementOrId, target_obj: ElementOrId): void'''

places mobile_obj on target_obj, set the absolute positions and centers the mobile_obj on target_obj,
effect is immediate

This is not really an animation, but placeOnObject is frequently used before starting an animation.

Example:
<pre>
// (We just created an object "my_new_token")

// Place the new token on current player board
this.placeOnObject( "my_new_token", "overall_player_board_"+this.player_id );

// Then slide it to its position on the board
this.slideToObject( "my_new_token", "a_place_on_board" ).play();
</pre>

'''this.placeOnObjectPos(mobile_obj: ElementOrId, target_obj: ElementOrId, target_x: number, target_y: number): void'''

This method works exactly like placeOnObject, except than you can specify some (x,y) coordinates (in px). This way, the center of "mobile_obj" will be placed to the specified x,y position relatively to the center of "target_obj".

''Note: the placement works differently from this.slideToObjectPos'', since coordinates are calculated based on the center of objects.

'''this.attachToNewParent(mobile_obj: ElementOrId, target_obj: ElementOrId): void'''

With this method, you change the HTML parent of "mobile_obj" element without moving it.
"target_obj" is the new parent of this element. The beauty of
attachToNewParent is that the mobile_obj element DOES NOT MOVE during this process.

What happens is that the method calculate a relative position of mobile_obj to make sure it does not move after the HTML parent changes.

Why using this method?

Changing the HTML parent of an element can be useful for the following reasons:
* When the HTML parent moves, all its child are moving with them. If some game elements is no more linked with a parent HTML object, you may want to attach it to another place.
* The z_order (vertical order of display) depends on the position in the DOM, so you may need to change the parent of some game elements when they are moving in your game area.

'''CAREFUL''': this function destroys original object and places a clone onto a new parent, this will break all references to this HTML element (ex: dojo.connect).
If you need version that does not destroy the object but the same otherwise see [[BGA_Studio_Cookbook#Attach_to_new_parent_without_destroying_the_object]]

== Animations ==

===Dojo Animations===

BGA animations is based on Dojo Animation ([http://dojotoolkit.org/documentation/tutorials/1.8/animation/ see tutorial here]).

However, most of the time, you can just use methods below, which are built on top of Dojo Animation.

Note: one interesting method from Dojo that could be useful from time to time is "Dojo.Animation". It allows you to make any CSS property "slide" from one value to another.

Note 2: the slideTo methods are not compatible with CSS transform (scale, zoom, rotate...). If possible, avoid using CSS transform on nodes that are being slided. Eventually, the only possible solution to make these 2 compatible is to disable all CSS transform properties, use slideToObjectPos/placeOnObjectPos, and then apply them again.

===Sliding===

'''this.slideToObject(mobile_obj: ElementOrId, target_obj: ElementOrId, duration?: number, delay?: number): Animation'''

You can use slideToObject to "slide" an element to a target position.

Sliding element on the game area is the recommended and the most used way to animate your game interface. Using slides allow players to figure out what is happening on the game, as if they were playing with the real boardgame.

The parameters are:
* mobile_obj: the ID of the object to move. This object must be "relative" or "absolute" positioned.
* target_obj: the ID of the target object. This object must be "relative" or "absolute" positioned. Note that it is not mandatory that mobile_obj and target_obj have the same size. If their size are different, the system slides the center of mobile_obj to the center of target_obj.
* duration: (optional) defines the duration in millisecond of the slide. The default is 500 milliseconds.
* delay: (optional). If you defines a delay, the slide will start only after this delay. This is particularly useful when you want to slide several object from the same position to the same position: you can give a 0ms delay to the first object, a 100ms delay to the second one, a 200ms delay to the third one, ... this way they won't be superposed during the slide.

BE CAREFUL: The method returns an dojo.fx animation, so you can combine it with other animation if you want to. It means that you have to call the "play()" method, otherwise the animation WON'T START.

Example:
<pre>
this.slideToObject( "some_token", "some_place_on_board" ).play();
</pre>

'''this.slideToObjectPos(mobile_obj: ElementOrId, target_obj: ElementOrId, target_x: number, target_y: number, duration?: number, delay?: number): Animation'''

This method does exactly the same as "slideToObject", except than you can specify some (x,y) coordinates. This way, "mobile_obj" will slide to the specified x,y position relatively to "target_obj".

Example: slide a token to some place on the board, 10 pixels from the top:
<pre>
this.slideToObjectPos( "some_token", "some_place_on_board", 0, 10 ).play();
</pre>

'''this.slideTemporaryObject(mobile_obj_html: string, parent: ElementOrId, from: ElementOrId, to: ElementOrId, duration?: number, delay?: number): Animation'''

This method is useful when you want to slide a temporary HTML object from one place to another. As this object does not exists before the animation and won't remain after, it could be complex to create this object (with dojo.place), to place it at its origin (with placeOnObject) to slide it (with slideToObject) and to make it disappear at the end.

slideTemporaryObject does all of this for you:
* mobile_obj_html is a piece of HTML code that represent the object to slide.
* parent is the ID of an HTML element of your interface that will be the parent of this temporary HTML object.
* from is the ID of the origin of the slide.
* to is the ID of the target of the slide.
* duration/delay works exactly like in "slideToObject"

Example:
<pre>
this.slideTemporaryObject( '<div class="token_icon"></div>', 'tokens', 'my_origin_div', 'my_target_div' ).play();
</pre>

===Destroy===
'''this.slideToObjectAndDestroy(mobile_obj: ElementOrId, target_obj: ElementOrId, duration?: number, delay?: number): void'''

This method is a handy shortcut to slide an existing HTML object to some place then destroy it upon arrival. It can be used for example to move a victory token or a card from the board to the player panel to show that the player earns it, then destroy it when we don't need to keep it visible on the player panel.

It works the same as this.slideToObject and takes the same arguments, but it starts the animation.

CAREFUL: Make sure nothing is creating the same object at the same time the animation is running, because this will cause some random disappearing effects

Example:
<pre>
this.slideToObjectAndDestroy( "some_token", "some_place_on_board", 1000, 0 );
</pre>

'''this.fadeOutAndDestroy( node: string | Element, duration?: number, delay?: number):''' '''void'''

This function fade out the target node, then destroy it. Its starts the animation.
* duration/delay works exactly like in "slideToObject"

Example:
<pre>
this.fadeOutAndDestroy( "a_card_that_must_disappear" );
</pre>

CAREFUL: the HTML node still exists until during few milliseconds, until the fadeOut has been completed.
Make sure nothing is creating same object at the same time as animation is running, because you will be some random dissapearing effects

===Rotating elements===

This example combines "Dojo.Animation" method and a CSS property transform that allow you to rotate the element.
<pre>
// node is Element we rotating
var animation = new dojo.Animation({
curve: [fromDegree, toDegree],
onAnimate: (v) => {
node.style.transform = 'rotate(' + v + 'deg)';
}
});

animation.play();
</pre>

BGA has its own interface to rotate

'''this.rotateTo(node: string | Element, degree: number): void'''

It starts the animation, and stored the rotation degree in the class, so next time you rotate object - it is additive.
There is no animation hooks in this one, if you need to change any parameters use dojo animation above.

There is also '''rotateInstantTo''' with same signature which does not animate

===Animation Callbacks===

If you wish to run some code only after an animation has completed you can do this by linking a callback method to 'onEnd'.

<pre>
var animation_id = this.slideToObject( mobile_obj, target_obj, 500 );
dojo.connect(animation_id, 'onEnd', () => {
// do something here
});
animation_id.play();
</pre>

If you wish to call a second animation after the first (rather than general code) then you can use a dojo animation chain (see tutorial referenced above).

== Players input ==

=== Connecting ===
'''dojo.connect(element: Element, event: string, context: object, method: eventHandler): any'''

'''dojo.connect(element: Element, event: string, hander: eventHandler): any'''

Used to associate a player event with one of your notification methods.

Example: associate a click on an element ("my_element") with one of our methods ("onClickOnMyElement"):
<pre>
dojo.connect( $('my_element'), 'onclick', this, 'onClickOnMyElement' );
</pre>

Same idea but base on query (i.e. all element of 'pet' class)
dojo.query(".pet").connect('onclick', this, 'onPet');

Note: if you need to disconnect the handler you have to store handler returned from this method, i.e.

<pre>
var handler = dojo.connect(...);
...
dojo.disconnect(handler);
</pre>

If you don't store the handler - you have to destroy the object to disconnect it

Typical function that implements the input handler will look like this

<pre>
onPet: function(event) {
var id = event.currentTarget.id;
console.log('onPet ' + id);
dojo.stopEvent(event);
if (this.gamedatas.gamestate.name == 'playerTurnPet') {
this.bgaPerformAction('actPlayPet', {card: id});
} else {
this.showMoveUnauthorized();
}
}
</pre>

'''this.connect(element: ElementOrId, event: string, method: eventHandler): void'''

Used to associate a player event with one of your notification methods.

this.connect( $('my_element'), 'onclick', 'onClickOnMyElement' );

Or you can use an in-place handler

this.connect( $('my_element'), 'onclick', (e) => { console.log('boo'); } );

Note that this function stores the connection handler. That is the only real difference between '''this.connect''' and '''dojo.connect'''. If you plan to destroy the element you connected, you '''must''' call this.disconnect() to prevent memory leaks.
This function is mainly for permanent objects - if you just want to connect the temp object you should probably not use this method but use dojo.connect which won't require any clean-up.

'''this.connectClass(cssClassName: string, event: string, method: eventHandler): void'''

Same as connect(), but for all the nodes set with the specified cssClassName.

this.connectClass('pet', 'onclick', 'onPet');

'''this.disconnect(element: ElementOrId, event: string): void'''

Disconnect event handler (previously registered with this.connect or this.connectClass).

this.disconnect( $('my_element'), 'onclick');

Note: dynamic connect/disconnect is for advanced cases ONLY, you should always connect elements statically if possible, i.e. in setup() method.

'''this.disconnectAll(): void'''

Disconnect all previously registed event handlers (registered via this.connect or this.connectClass)

this.disconnectAll();

=== Actions ===

'''this.bgaPerformAction(action: string, args?: object, options: object = { lock: true, checkAction: true }): Promise<void>'''

Triggers an action on the backend. This is a combination of checkAction and ajaxcall, returning a Promise which resoves when ajaxcall ends.

This method must be used to send a player input to the game server. '''It should not be triggered programmatically''', especially not in loops, in callbacks, in notifications, or in onEnteringState/onUpdateActionButtons/onLeavingState, in order not to create race conditions or break replay game and tutorial features. It should be used only in reaction to a user action in the interface.

* action: name of the action, as it is written in "possibleactions" of the current state.
* args: an object containing the call parameters to send to the action
* options: options to tweak the call with some defaults. Default is <code>{ lock: true, checkAction: true }</code>.

Example of a standard call without args:
this.bgaPerformAction('pass');

Example of a standard call with action args:
this.bgaPerformAction('actPlayCard', { id: this.selectedCardId });

Example of a call without checking action (because player is inactive in a multiactive state):

this.bgaPerformAction('actChangeMind', {}, { checkAction: false });

Example of a call without lock (because of a special action not directly related to the game flow):

this.bgaPerformAction('actSetAutoBid', { alwaysBidUntil: 500 }, { lock: false, checkAction: false });

Example of call with reaction to exception:
this.bgaPerformAction('actPlayCard', { id: this.selectedCardId }).catch(()=>{ this.selectedCardId = undefined; });

Example of call with reaction to success:
this.bgaPerformAction('actPlayCard', { id: this.selectedCardId }).then(()=>{ this.unselectAll(); });

'''this.ajaxcall(url, parameters, obj_callback, callback, callback_anycase?, ajax_method?: string)'''

''Note: bgaPerformAction is a simpler way to use ajax calls, ajaxcall stays in the doc for legacy reasons only and should not be used in new projects.''

Same warning as '''this.bgaPerformAction''' about using on user action only.

* url: the url of the action to perform. For a game, it must be: "/<mygame>/<mygame>/myAction.html"
* parameters: an array of parameter to send to the game server.
** Note that "lock: true" must always be specified in this list of parameters in order the interface can be locked during the server call. Cannot use lock: false - to not lock it has to be undefined.
** Note: Restricted parameter names (please don't use them):
*** "action"
*** "module"
*** "class"
* obj_callback: must be set to "this".
* callback (non-optional but rarely used): a function to trigger when the server returns result and everything went fine (not used, as all data handling is done via notifications).
* callback_anycase: (optional) a function to trigger when the server returns ok OR error. If no error this function is called with parameter value false. If an error occurred, the first parameter will be set to true, the second will contain the error message sent by the PHP back-end, and the third will contain an error code.
* ajax_method: (optional and rarely used) if you need to send large amounts of data (over 2048 bytes), you can set this parameter to 'post' (all lower-case) to send a POST request as opposed to the default GET. This works, but was not officially documented, so only use if you really need to.

Usage:
<pre>
this.ajaxcall( '/mygame/mygame/actMyAction.html', { lock: true,
arg1: myarg1,
arg2: myarg2
}, this, (result)=>{} );
</pre>

'''this.checkAction(action: string, nomessage?: boolean): boolean '''

Check if player can do the specified action by taking into account:
* if interface is locked it will return false and show message "An action is already in progress", unless nomessage set to true
* if player is not active it will return false and show message "This is not your turn", unless nomessage set to true
* if action is not in list in possible actions (defined by "possibleaction" in current game state) it will return false and show "This move is not authorized now" error (unconditionally).
* otherwise returns true
Example:
<pre>
function onClickOnGameElement( evt ) {
if( this.checkAction( "actMyAction" ) ) {
// Do the action
}
}
</pre>

'''this.checkPossibleActions(action: string): boolean'''

* this is independent of the player being active, so can be used instead of this.checkAction(). This is particularly useful for multiplayer states when the player is not active in a 'player may like to change their mind' scenario. Unlike this.checkAction, this function does NOT take interface locking into account

* if action is not in list in possible actions (defined by "possibleaction" in current game state) it will return false and show "This move is not authorized now" error (unconditionally).
* otherwise returns true

function onChangeMyMind( evt ) {
if( this.checkPossibleActions( "actMyAction" ) ) {
// Do the action
}
}

'''this.checkLock(nomessage?: boolean): boolean'''

When using "lock: true" in ajax call you can use this function to check if interface is in lock state (it will be locked during server call and notification processing).
This check can be used to block some other interactions which do not result in ajaxcall or if you want to suppress errors. Note: normally you only need to use this.checkAction(...), this is for advanced cases.

It will also show error unless nomessage is set to true

function onChangeMyMind( evt ) {
if( this.checkLock() ) {
// Do the action
}
}

== Notifications ==

When something happens on the server side, your game interface Javascript logic received a notification.
If you have not done so yet check what notification are in [[Main_game_logic:_yourgamename.game.php#Notifications]]

Here's how you can handle these notifications on the client side.

=== Subscribe to notifications ===

'''dojo.subscribe(notif_type: string, callback_obj: Object, handler: string|handler)'''
* notif_type - notification type/name send by php server
* callback_obj - usually this
* handler - if string method of callback_obj with name name is called, when notification is called, with notification object as parameter (see below)

Your Javascript "setupNotifications" method is the place where you can subscribe to notifications from your PHP code.

Here's how you associate one of your Javascript method to a notification "playDisc" (from Reversi example):

<pre>
setupNotifications: function() {
...
dojo.subscribe('playDisc', this, "notif_playDisc");
},
</pre>

Note: the "playDisc" corresponds to the name of the notification you define it in your PHP code, in your "notifyAllPlayers" or "notifyPlayer" method.

Then, you have to define your "notif_playDisc" method:

<pre>
notif_playDisc: function(notif) {
// Remove current possible moves (makes the board more clear)
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );
this.addDiscOnBoard( notif.args.x, notif.args.y, notif.args.player_id );
},
</pre>

In a notification handler like our "notif_playDisc" method, you can access all notifications arguments with "notif.args".

Example:

PHP

<pre>
$this->notifyAllPlayers( "apples", clienttranslate('player takes ${count} apples'), [ "count" => 3 ] );
</pre>

JavaScript

<pre>
setupNotifications: function() {
dojo.subscribe( 'apples', this, 'notif_apples' );
},

notif_apples: function(notif) {
//You can access the "count" like this:
alert("count = " + notif.args.count);
}
</pre>

=== The notification Object received by client ===

When sending a notification on your PHP, the client side will receive an Object with the following attributes:

* type - type of the notification (as passed by php function)
* log - the log string passed from php notification
* args - This is the arguments that you passed on your notification method on php
* bIsTableMsg - is true when you use [[Main_game_logic:_yourgamename.game.php#NotifyAllPlayers|NotifyAllPlayers]] method (false otherwise)
* channelorig - information about table ID (formatted as : "/table/t[TABLE_NUMBER]")
* gamenameorig - name of the game
* move_id - ID of the move associated with the notification
* table_id - ID of the table (comes as string)
* time - UNIX GMT timestamp
* uid - unique identifier of the notification
* h - unknown

'' Note that those information were inferred from observation on console log. If an Admin can confirm/correct (and remove this line), you're welcome :)''

=== Ignoring notifications ===

Sometimes you need to ignore some notification on client side. You don't want them to be shown in game log and you don't want them to be handled.

The most common use case is when a player gets private information. They will receive a specific notification (such as "You received Ace of Heart"), while other players would receive more generic notification ("Player received a card").

In X.game.php
<pre>
$this->notifyAllPlayers("dealCard", clienttranslate('${player_name} received a card'), [
'player_id' => $playerId,
'player_name' => $this->getActivePlayerName()
]);

$this->notifyPlayer($playerId, "dealCardPrivate", clienttranslate('You received ${cardName}'), [
"type" => $card["type"],
"cardName" => $this->getCardName($card["type"])
]);
</pre>

The problem with this approach is that the active player will receive two notifications:
* Player1 received a card
* You received Ace of Hearts

Hence, notification ignoring.

NOTE: You can think that it would be possible to send such notification to all players except active just by using notifyPlayer and it seems to work. The problem however is that table spectators would miss such notification and their user interface (and game log) wouldn't be updated. Since there is no way to send notification just to spectators, ignoring the notification (or "filtering") is the only reasonable solution.

'''setIgnoreNotificationCheck(notif_type: string, predicate: ((notif: Notif)=>boolean))'''
This method will set a check whether any of notifications of specific type should be ignored.

The parameters are:
* notif_type: type of the notification
* predicate (notif => boolean): a function that will receive notif object and will return true if this specific notification should be ignored

Before dispatching any notification of this type, the framework will call predicate to check whether notification should be ignored, if it return true - the notification will be dispatched, i.e. logged or handled.

<pre>
this.notifqueue.setIgnoreNotificationCheck( 'dealCard', (notif) => (notif.args.player_id == this.player_id) );
</pre>

IMPORTANT: Remember that this notification is ignored on the client side, but was still received by the client. Therefore it shouldn't contain any private information as cheaters can get it. In other words this is not a way to hide information.

IMPORTANT: When a game is reloaded with F5 or when opening a turn based game, old notifications are replayed as history notification. They are used just to update the game log and are stripped of all arguments except player_id, i18n and any argument present in message. If you use and other argument in your predicate you should '''preserve''' it as explained [[Main_game_logic:_yourgamename.game.php#Notify_players|here]].

=== Synchronous notifications ===

When several notifications are received by your game interface, these notifications are processed immediately, one after the other, in the same exact order they have been generated in your PHP game logic.

However, sometimes, you need to give some time to the players to figure out what happened on the game before jumping to the next notification. Indeed, in many games, there are a lot of automatic actions, and the computer is going to resolve all these actions very fast if you don't tell it not to do so.

As an example, for Reversi, when someone is playing a disc, we want to wait 500 milliseconds before doing anything else in order the opponent player can figure out what move has been played.

Here's how we do this, right after our subscription:
<pre>
dojo.subscribe( 'playDisc', this, "notif_playDisc" );
this.notifqueue.setSynchronous( 'playDisc', 500 ); // Wait 500 milliseconds after executing the playDisc handler
</pre>

-----

It is also possible to control the delay timing dynamically (e.g., using notification args). As an example, maybe your notification 'cardPlayed' should pause for a different amount of time depending on the number or type of cards played.

For this case, use '''setSynchronous''' without specifying the duration and use '''setSynchronousDuration''' within the notification callback.

* NOTE: If you forget to invoke '''setSynchronousDuration''', the game will remain paused forever!

<pre>
setupNotifications: function () {
dojo.subscribe( 'cardPlayed', this, 'notif_cardPlayed' );
this.notifqueue.setSynchronous( 'cardPlayed' ); // wait time is dynamic
...
},

notif_cardPlayed: function (notif) {
// MUST call setSynchronousDuration

// Example 1: From notification args (PHP)
this.notifqueue.setSynchronousDuration(notif.args.duration);
...

// Or, example 2: Match the duration to a Dojo animation
var anim = dojo.fx.combine([
...
]);
anim.play();
this.notifqueue.setSynchronousDuration(anim.duration);
},
</pre>

You can also manually call this.notifqueue.setSynchronousDuration(0) once client operations are finished, but be careful that even fast replay still has a path to call it.

'''WARNING: combining synchronous and ignored notifications'''
You must be careful when combining dynamic synchronous durations (as described above) with ignored notifications. If you have a conditionally ignored notification like this (see below section):

<pre>this.notifqueue.setIgnoreNotificationCheck( 'myNotif', (notif) => (notif.args.player_id == this.player_id) /* or any other condition */ )</pre>

then you CANNOT do

<pre>this.notifqueue.setSynchronous('myNotif');</pre>

as, when the ignored check passes, the notification handler, in which `this.notifqueue.setSychronousDuration` is called, is never called and so the duration is never set and interface locking results.

The workaround is to set a "dummy" time:

<pre>this.notifqueue.setSynchronous('myNotif', 5000);</pre>

whose value is irrelevant but must be large enough to cover the time before the notification handler is called. The large value never actually comes into play because the notification is either ignored, or the synchronous duration is reset to a sensible value inside the handler.

=== Pre-defined notification types ===

'''tableWindow''' - This defines notification to display [[Game_interface_logic:_yourgamename.js#Scoring_dialogs|Scoring Dialogs]], see below.

'''message''' - This defines notification that shows on players log and have no other effect (technically any unhandled notification will do the same but its recommended to use this keyword for consistency)

// You can call this on php side without doing anything on client side
self::notifyAllPlayers( 'message', clienttranslate('hello'), [] );

'''simplePause''' - This notification will just delay other notifications, maybe useful if you know you need some extra time for animation or something. Requires a time parameter.

<pre>
self::notifyAllPlayers( 'simplePause', '', [ 'time' => 500] ); // time is in milliseconds
</pre>

Note: the following types are RESERVED by framework, do not use:

gameStateChange gameStateChangePrivateArg gameStateMultipleActiveUpdate newActivePlayer playerstatus yourturnack clockalert tableInfosChanged playerEliminated tableDecision archivewaitingdelay end_archivewaitingdelay replaywaitingdelay end_replaywaitingdelay replayinitialwaitingdelay end_replayinitialwaitingdelay aiPlayerWaitingDelay replay_has_ended updateSpectatorList wouldlikethink updateReflexionTime undoRestorePoint resetInterfaceWithAllDatas zombieModeFail zombieModeFailWarning aiError skipTurnOfPlayer zombieBack allPlayersAreZombie gameResultNeutralized playerConcedeGame showTutorial showCursor showCursorClick skipTurnOfPlayerWarning banFromTable resultsAvailable switchToTurnbased newPrivateState infomsg

== Tooltips ==

=== Adding static tooltips ===

'''this.addTooltip(nodeId: string, helpStringTranslated: string, actionStringTranslated: string, delay?: number): void'''

Add a simple text tooltip to the DOM node.

Specify 'helpStringTranslated' to display some information about "what is this game element?".
Specify 'actionStringTranslated' to display some information about "what happens when I click on this element?".

You must specify both of the strings. You can only use one and specify an empty string ('') for the other one.

When you pass text directly function _() must be used for the text to be marked for translation! Except for empty string.

Parameter "delay" is optional. It is primarily used to specify a zero delay for some game element when the tooltip gives really important information for the game - but remember: no essential information must be placed in tooltips as they won't be displayed in some browsers (see [[BGA_Studio_Guidelines|Guidelines]]).

Example:
<pre>
this.addTooltip( 'cardcount', _('Number of cards in hand'), '' );
</pre>

Note: this generates static tooltip and attaches to existing dom element, if you need to generate tooltip more dynamically you have to call that method every time information about object is updated or use completely different tehnique, see dynamic tooltips below.

'''this.addTooltipHtml(nodeId: string, html: string, delay?: number): void'''

Add an HTML tooltip to the DOM node (for more elaborate content such as presenting a bigger version of a card).

'''this.addTooltipToClass(cssClass: string, helpStringTranslated: string, actionStringTranslated: string, delay?: number ): void'''

Add a simple text tooltip to all the DOM nodes set with this cssClass. See more details above for this.addTooltip.
this.addTooltipToClass( 'meeple', _('This is A Meeple'), _('Click to tickle') );

IMPORTANT: all concerned nodes must exist and have IDs to get tooltips.

'''this.addTooltipHtmlToClass(cssClass: string, html: string, delay?: number): void'''

Add an HTML tooltip to to all the DOM nodes set with this cssClass (for more elaborate content such as presenting a bigger version of a card).

IMPORTANT: all concerned nodes must exist and have IDs to get tooltips.

=== Removing static tooltips ===

'''this.removeTooltip(nodeId: string): void'''

Remove a tooltip from the DOM node with given id.

=== Advanced tooltips ===

'''force tooltip to open'''

If you want to force tooltip to open in reaction to some other action, i.e. click you can do this

this.tooltips[id].open(id)

where id is the id of the tooltip node where tooltip was installed.

'''dynamic tooltips'''

See [[BGA_Studio_Cookbook#Dynamic_tooltips]]

'''tooltips on mobile'''

Tooltips is very unreliable on mobile, it is recommended to implement some other method to obtaining same information,
such as simple click handler in dedicated "Help" mode or provide dedicated clickable areas such as corner of card.

== Warning messages ==

Sometimes, there is something important that is happening in the game and you have to make sure all players get the message. Most of the time, the evolution of the game situation or the game log is enough, but sometimes you need something more visible.

Ex: someone fulfills one of the end of the game conditions, so this is the last turn.

'''this.showMessage(msg: string, type: string): void'''

showMessage shows a message in a big rectangular area on the top of the screen of the current player, and it dissapears after few seconds (also it will be in the log in some cases).

* "msg" is the string to display. It should be translated.
* "type" can be set to "info", "error", "only_to_log" or custom string. If set to "info", the message will be an informative message on a white background. If set to "error", the message will be an error message on a red background and it will be added to log. If set to "only_to_log", the message will be added to the game log but will not popup at the top of the screen.
If set to custom string, it will be transparent, to use custom type define "head_xxx" in css, where xxx is the type. For example if you want yellow warning, use "warning" as type and add this to css:
.head_warning {
background-color: #e6c66e;
}

Important: the normal way to inform players about the progression of the game is the game log. The "showMessage" is intrusive and should not be used often.

<pre>
notif_messageinfo: function(notif) {
if (!g_archive_mode) {
var message = this.format_string_recursive(notif.log, notif.args);
this.showMessage(_('Announcement:') + " " + message, 'info');
}
},
</pre>

Show message could be used on the client side to prevent user wrong moves before it is send to server.
Example from 'battleship':
<pre>
onGrid: function(event) {
if (checkIfPlayerTriesToFireOnThemselves(event)) {
this.showMessage(_('This is your own board silly!'), 'error');
return;
}
...
},
</pre>

'''this.showMoveUnauthorized(): void'''

Shows predefined user error that move is unauthorized now

<pre>
onPet: function(event) {
if (checkPet(event)==false) {
this.showMoveUnauthorized();
return;
}
...
},
</pre>

== Dialogs ==

=== Confirmation dialog ===

When an important action with a lot of consequences is triggered by the player, you may want to propose a confirmation dialog.

CAREFUL: the general guideline of BGA is to AVOID the use of confirmation dialogs. Confirmation dialogs slow down the game and bother players. The players know that they have to pay attention to each move when they are playing online.

The situations where you should use a confirmation dialog are the following:
* It must not happen very often during a game.
* It must be linked to an action that can really "kill a game" if the player does not pay attention.
* It must be something that can be done by mistake (ex: a link on the action status bar).

'''this.confirmationDialog(message: string, yesHandler: (param: any) => void, noHandler?: (param: any) => void, param?: any): void'''

* message - message will be shown to user, use _() to translate
* yesHandler - non-optional handler to be called on yes
* noHandler - optional handler to called on no
* param - if specified, it will be passed to both handlers
NOTE: this is async function, it does not return anything and you should not do anything after, you must do everything in handlers

How to display a confirmation dialog:
<pre>
this.confirmationDialog(_("Are you sure you want to bake a pie?"), () => {
this.bakeThePie();
});
return; // nothing should be called or done after calling this, all action must be done in the handler
</pre>
With param and both handlers
<pre>
this.confirmationDialog(_("Are you sure you want to bake a pie?"),
(ingredient) => this.bakeThePie(ingredient),
(ingredient) => console.log(`cancelled baking of ${ingredient}`),
'apple');
</pre>

=== Multiple choice dialog ===

You can use this dialog to give user a choice with small amount of options

'''this.multipleChoiceDialog(message: string, choices: string[], callback: (choice: number) => void): void'''
* message - message will be shown to user, use _() to translate
* choices - array of choices
* callback - non-optional handler to be called on choice made, the choice parameter is the INDEX of the choice from the array of choices

NOTE: this is async function, it does not return anything and you should not do anything after, you must do everything in handlers
NOTE: there is no cancel handler, so make sure you gave user a choice to get out of it

Example:
<pre>
const keys = ["0", "1", "5", "10"];
this.multipleChoiceDialog(_("How many bugs to fix?"), keys, (choice) => {
if (choice==0) return; // cancel operation, do not call server action
var bugchoice = keys[choice]; // choice will be 0,1,2,3 here
this.bgaPerformAction("fixBugs", { number: bugchoice });
});
return; // must return here
</pre>

=== Generic Dialogs ===

As a general rule, you shouldn't use dialogs windows.

BGA guidelines specify that all game elements should be displayed on the main screen. Players can eventually scroll down to see game elements they don't need to see anytime, and you may eventually create anchors to move between game area section. Of course dialogs windows are very practical, but the thing is: all players know how to scroll down, and not all players know how to show up your dialog window. In addition, when the dialog shows up, players can't access the other game components.

Sometimes although, you need to display a dialog window. Here is how you do this:

// Create the new dialog over the play zone. You should store the handler in a member variable to access it later
this.myDlg = new ebg.popindialog();
this.myDlg.create( 'myDialogUniqueId' );
this.myDlg.setTitle( _("my dialog title to translate") );
this.myDlg.setMaxWidth( 500 ); // Optional

// Create the HTML of my dialog.
// The best practice here is to use [[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl#Javascript_templates|Javascript templates]]
var html = this.format_block( 'jstpl_myDialogTemplate', {
arg1: myArg1,
arg2: myArg2,
...
} );

// Show the dialog
this.myDlg.setContent( html ); // Must be set before calling show() so that the size of the content is defined before positioning the dialog
this.myDlg.show();

// Now that the dialog has been displayed, you can connect your method to some dialog elements
// Example, if you have an "OK" button in the HTML of your dialog:
dojo.connect($('my_ok_button'), 'onclick', this, (event) => {
event.preventDefault();
this.myDlg.destroy();
});

If necessary, you can remove the default top right corner 'close' icon, or replace the function called when it is clicked:
// Removes the default close icon
this.myDlg.hideCloseIcon();

// Replace the function call when it's clicked
this.myDlg.replaceCloseCallback((event) => { ... });

=== Scoring dialogs ===

Sometimes at the end of a round you want to display a big table that details the points wins in each section of the game.

Example: in Hearts game, we display at the end of each round the number of "heart" cards collected by each player, the player who collected the Queen of Spades, and the total number of points loose by each player.

Scoring dialogs are managed entirely on '''PHP side''', but they are described here as their effects are visible only on client side.

Displaying a scoring dialog is quite simple and is using a special notification type: "tableWindow":
<pre>
// on PHP side:
$this->notifyAllPlayers( "tableWindow", '', array(
"id" => 'finalScoring',
"title" => clienttranslate("Title of the scoring dialog"),
"table" => $table
));
</pre>

The "table" argument is a 2 dimensional PHP array that describes the table you want to display, line by line and column by column.

Example: display an 3x3 array of strings
<pre>
$table = [
[ "one", "two", "three" ], // This is my first line
[ "four", "five", "six" ], // This is my second line
[ "seven", "height", "nine" ] // This is my third line
];
</pre>

As you can see above, in each "cell" of your array you can display a simple string value. But you can also display a complex value with a template and associated arguments like this:
<pre>
$table = [
[ "one", "two", [ "str" => clienttranslate("a string with an ${argument}"), "args" => [ 'argument' => 'argument_value' ] ] ],
[ "four", "five", "six" ],
[ "seven", "height", "nine" ]
];
</pre>

This is especially useful when you want to display player names with colors. Example from "Hearts":
<pre>
$firstRow = [ '' ];
foreach( $players as $player_id => $player ) {
$cell = [ 'str' => '${player_name}',
'args' => [ 'player_name' => $player['player_name'] ],
'type' => 'header'
];
$firstRow[] = $cell;
}
$table[] = $firstRow;
...
</pre>

You can also use three extra attributes in the parameter array for the notification:
* '''header''': the content for this parameter displays before the table (also, the html will be parsed and player names will be colored according to the current game colors).
* '''footer''': the content for this parameter displays after the table (no parsing for coloring the player names)
* '''closing''': if this parameter is used, a button will be displayed with this label at the bottom of the popup and will allow players to close it (more easily than by clicking the top right 'cross' icon).

<pre>
$this->notifyAllPlayers( "tableWindow", '', [
"id" => 'finalScoring',
"title" => clienttranslate("Title of the scoring dialog"),
"table" => $table,
"header" => ['str' => clienttranslate('Table header with parameter ${number}'),
'args' => [ 'number' => 3 ],
],
"footer" => '<div class="myfoot"></div>',
"closing" => clienttranslate( "Closing button label" )
] );
</pre>

Note: currently id is not used - so you cannot access resulting div by id on js side
Note: any traslatable stirng have to be wrapped by clienttranslate() on top level OR it has to be recursive template.

DO NOT DO THIS:
<pre>
"footer" => '<div>'.clienttranslate( "The end" ).'</div>', // this will not work for translations!!!
</pre>

=== Scoring animated display ===

Sometimes, you may want to display a score value over an element to make the scoring easier to follow for the players (Terra Mystica final scoring for example).
You can do it with:

'''this.displayScoring(anchor_id: string, color: string, score: number | string, duration?: number, offset_x?: number, offset_y?: number): void'''

'''anchor_id''': ID of the html element to place the animated score onto (without the '#')

'''color''': hexadecimal RGB representation of the color (should be the color of the scoring player), but without a leading '#'. For instance, 'ff0000' for red.

'''score''': numeric score to display, prefixed by a '+' or '-'

'''duration''': animation duration in milliseconds (optional, default is 1000)

'''offset_x''' and '''offset_y''': if both offset_x and offset_y are defined and not null, apply the following offset (in pixels) to the scoring animation.
Note that the score is centered in the anchor, so the offsets might have to be negative if you calculate the position.

Note: if you want to display successively each score, you can use ''this.notifqueue.setSynchronous()'' function.
<pre>
setupNotifications: function() {
dojo.subscribe( 'displayScoring', this, "notif_displayScoring" );
...
}
...

notif_displayScoring: function(notif) {
const duration = notif.args.duration?notif.args.duration:1000;
this.notifqueue.setSynchronous('displayScoring', duration );
this.displayScoring( notif.args.target, notif.args.color, notif.args.score, duration);
},
</pre>

=== Speech bubble ===

For better interactivity in some games (Love Letter for example), you may use comic book style speech bubbles to express the players voices.
This is done with showBubble:

'''this.showBubble(anchor_id: string, text: string, delay?: number, duration?: number, custom_class?: string): void'''

* anchor_id - where to attach the bubble
* text - what to put in bubble, can be html
* delay - delay in milliseconds (optional, default 0)
* duration - duration of animation in milliseconds (optional, default 3000)
* custom_class - extra class to add to bubble (optional), if you need to override the default bubble style

<pre>
this.showBubble('meeple_2', _('Hello'), 0, 1000, 'pink_bubble');
</pre>

<pre>
notif_speechBubble(notif) {
var html = this.format_string_recursive(notif.args.text, notif.args.args);
this.showBubble(notif.args.target, html, notif.args.delay ?? 0, notif.args.duration ?? 1000);
},
</pre>

'''Warning''': if your bubble could overlap other active elements of the interface (buttons in particular), as it stays in place even after disappearing, you should use a custom class to give it the style "pointer-events: none;" in order to intercept click events.

Note: If you want this visually, but want to take complete control over this bubble and its animation (for example to make it permanent) you can just use div with 'discussion_bubble' class on it, and content of div is what will be shown.

== Translations ==

See [[Translations]]

== Players panels ==

=== Update players score ===

The column player_score from the player table is automatically loaded into this.scoreCtrl and therefore into the stars location on the player board. This occurs sometime after the game setup() function. However this score must be updated as the game progresses using notifications.

Note: this.scoreCtrl[player_id] is object of class [[Counter]], you can use other counter API.

Increase a player score (with a positive or negative number):

<pre>
this.scoreCtrl[ player_id ].incValue( score_delta );
</pre>

Set a player score to a specific value:

<pre>
this.scoreCtrl[ player_id ].setValue( new_score );
</pre>

Set a player score to a specific value with animation:

<pre>
this.scoreCtrl[ player_id ].toValue( new_score );
</pre>

Typical usage would be (that will process 'score' notification):
<pre>
setupNotifications : function() {
...
dojo.subscribe('score', this, "notif_score");
},
notif_score: function(notif) {
this.scoreCtrl[notif.args.player_id].setValue(notif.args.player_score);
},
</pre>

=== Adding stuff to player's panel ===

At first, create a new "JS template" string in your template (tpl) file:

(from Gomoku example)
<pre>
var jstpl_player_board = '\<div class="cp_board">\
<div id="stoneicon_p${id}" class="gmk_stoneicon gmk_stoneicon_${color}"></div><span id="stonecount_p${id}">0</span>\
</div>';
</pre>

Then, you add this piece of code in your JS file to add this template to each player panel:

<pre>
// Setting up player boards
for( var player_id in gamedatas.players )
{
var player = gamedatas.players[player_id];

// Setting up players boards if needed
var player_board_div = $('player_board_'+player_id);
dojo.place( this.format_block('jstpl_player_board', player ), player_board_div );
}
</pre>

(Note: the code above is of course from your "setup" function in your Javascript).

Very often, you have to distinguish current player and others players. In this case, you just have to create another JS template (ex: jstpl_otherplayer_board) and use it when "player_id" is different than "this.player_id".

=== Fixing Player Panel heights ===

You may find that the player panels don't automatically resize when adding something to (or removing something from) a player panel while the display is in portrait mode (i.e. the player summary panels are at the top of the screen rather than down the right side).

When this happens, call <pre>this.adaptPlayersPanels();</pre> This recalculates the layout and also adjusts the position of the actionbar for you.

=== Player's panel disabling/enabling ===

'''this.disablePlayerPanel(player_id: number): void'''

Disable given player panel (the panel background become gray).

Usually, this is used to signal that this played passes, or will be inactive during a while.

Note that the only effect of this is visual. There are no consequences on the behaviour of the panel itself.

'''this.enablePlayerPanel(player_id:number): void'''

Enable a player panel that has been disabled before.

'''this.enableAllPlayerPanels(): void'''

Enable all player panels that has been disabled before.

=== Player order ===

'''this.updatePlayerOrdering(): void'''

This function makes sure that player order in player's panel matches this.gamedatas.playerorder and its normally called by framework.
You can call it yoursel if you change this.gamedatas.playerorder from notification.
Also you can override this function to change defaults OR insert a non-player panel [[BGA_Studio_Cookbook#Inserting_non-player_panel]].

=== Counters ===
Note: there is bga component called "ebg/counter" this API is not using it, these methods
below declared right in core game. If you need animation for counters use ebg/counter

To use this API just create a counter dom element like this (class does not really matter)
<pre>
<div class="counter" id="bread"></div>
<div class="counter" id="coin"></div>
</pre>
The "bread" will the counter name.

The php code should send all "counters" data from getAllDatas() method like this

game.php
<pre>
protected function getAllDatas() {
// (the key must match counter_name)
$result['counters']=[
'bread' => [
'counter_name' => 'bread',
'counter_value' => 3
],
'coin' => [
'counter_name' => 'coin',
'counter_value' => 5
]
];
return $result;
}
</pre>

'''setCounter(counter_name: stirng, new_value: string | number): void'''

updates the global this.gamedatas.counters and value of node $(counter_name)
<pre>
notif_counter: function(notif) {
this.setCounter(notif.args.counter_name, notif.args.counter_value);
},
</pre>

'''incCounter(counter_name: string, delta: number): void'''
<pre>
notif_counter : function(notif) {
this.incCounter(notif.args.counter_name, notif.args.inc);
},
</pre>

'''updateCounters(counters: object): void'''

Useful for updating game counters in the player panel (such as resources).
'counters' arg is map of counters (the key must match counter_name)
{
'bread': {
'counter_name' : 'bread',
'counter_value' => 3
},
'coin': {
'counter_name' : 'coin',
'counter_value' => 5
}
}
All counters MUST be referenced in this.gamedatas.counters (means they should be send from php) and will be updated.
DOM objects referenced by 'counter_name' will have their innerHTML updated with 'counter_value'.

Usually you call this from notification

<pre>
notif_counter : function(notif) {
this.updateCounters(notif.args.counters);
},
</pre>

== BGA GUI components ==

BGA framework provides some useful ready-to-use components for the game interface:

[[Studio#BGA_Studio_game_components_reference]]

Note that each time you are using an additional component, you must declare it at the top of your Javascript file in the list of modules used.

Example if you are using "ebg.stock":
<pre>
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/stock" /// <=== we are using ebg.stock module
],
</pre>

== BGA Buttons ==

=== Basic Button ===

'''this.addActionButton(id: string, label: string, method: string | eventhandler, destination?: string, blinking?: boolean, color?: string): void'''

You can use this method to add an action button in the main action status bar (or other places).

Arguments:
* id: an element ID that should be unique in your HTML DOM document.
* label: the text of the button. Should be translatable (use _() function). Note: this can also be any html, such as "<div class='brick'></div>", see example below on how to make image action buttons.
* method: the name of your method that must be triggered when the player clicks on this button (can be name of the method on game class or handler).
* destination (optional): id of parent on where to add button, ONLY use in rare cases if location is not action bar. Use '''null''' as value if you need to specify other arguments.
* blinking (optional): if set to '''true''', the button is going blink to catch player's attention. Please DO NOT abuse blinking button. If you need button to blink after some time passed add class 'blinking' to the button later.
* color: could be '''blue''' (default), '''red''','''gray''' or '''none'''.

You should only use this method in your "onUpdateActionButtons" method. Usually, you use it like this:

<pre>
onUpdateActionButtons: function( stateName, args ) {
if (this.isCurrentPlayerActive()) {
switch( stateName ) {
case 'giveCards':
this.addActionButton( 'giveCards_button', _('Give selected cards'), 'onGiveCards' );
this.addActionButton( 'pass_button', _('Pass'), () => this.bgaPerformAction('actPass') );
break;
}
}
},
</pre>

In the example above, we are adding a "Give selected cards" button in the case we are on game state "giveCards". When player clicks on this button, it triggers our "onGiveCards" method.

Example using blinking red button:
<pre>
this.addActionButton( 'button_confirm', _('Confirm?'), 'onConfirm', null, true, 'red');
</pre>

If you want to call the handler with arguments, you can use arrow functions, like this:
<pre>
this.addActionButton( 'commit_button', _('Confirm'), () => this.onConfirm(this.selectedCardId), null, false, 'red');
</pre>

=== Image Button ===

You can use the same method, but add extra class to a button to disable the padding and style it, i.e.
<pre>
this.addActionButton( 'button_brick', '<div class="brick"></div>', ()=>{... on brick ...}, null, null, 'gray');
dojo.addClass('button_brick','bgaimagebutton');
</pre>

where

<pre>
.bgaimagebutton {
padding: 0px 12px;
min-height: 28px;
border: none;
}
</pre>

If you use this a lot, you can define a helper function, i.e.
<pre>
/**
* This method can be used instead of addActionButton, to add a button which is an image (i.e. resource). Can be useful when player
* need to make a choice of resources or tokens.
*/
addImageActionButton: function(id, div, handler, bcolor, tooltip) {
if (typeof bcolor == "undefined") {
bcolor = "gray";
}
// this will actually make a transparent button id color = gray
this.addActionButton(id, div, handler, null, false, bcolor);
// remove border, for images it better without
dojo.style(id, "border", "none");
// but add shadow style (box-shadow, see css)
dojo.addClass(id, "shadow bgaimagebutton");
// you can also add additional styles, such as background
if (tooltip) {
dojo.attr(id, "title", tooltip);
}
return $(id);
},
</pre>

=== Disabling Button ===

You can disable the '''bgabutton''' by adding the css class '''disabled''' in you js. The disabled button is still visible but is grey and not clickable.
For example in the '''onUpdateActionButtons''' :
<pre>
this.addActionButton('play_button_id', _('Play 1 to 3 cards'), 'playFunctionButton');
if (condition) {
dojo.addClass('play_button_id', 'disabled');
}
</pre>

=== Custom Buttons ===

You can create a custom button, but the BGA framework provides a standard button that requires only .css classes: '''bgabutton''' and '''bgabutton_${color}'''.

'''Examples:'''

<pre>
<a href="#" id="my_button_id" class="bgabutton bgabutton_blue"><span>My blue button</span></a>

<a href="#" id="my_button_id" class="bgabutton bgabutton_red bgabutton_big"><span>My big red button</span></a>
</pre>

'''Note''': To see it in action, check out ''Coloretto''.

=== Button outside of action bar ===

Use addActionButton() method with destination argument set
<pre>
this.addActionButton( 'commit_button', _('Confirm'), 'onConfirm', 'player_board', true, 'red');
</pre>

in example above the button will be place on object with id 'player_board'

== Image loading ==

See also [[Game_art:_img_directory]].

'''Be careful''': by default, ALL images of your img directory are loaded on a player's browser when he loads the game. For this reason, don't let in your img directory images that are not useful, otherwise it's going to slowdown the game load.

'''this.dontPreloadImage(image_file_name: string)'''

Using dontPreloadImage, you tell the interface to not preload a specific image in your img directory.

Example of use:
<pre>
this.dontPreloadImage( 'cards.png' );
</pre>

This is particularly useful if for example you have 2 different themes for a game. To accelerate the loading of the game, you can specify to not preload images corresponding to the other theme.

Another example of use: in "Gosu" game with Kamakor extension, you play with 5 sets of cards among 10 available. Cards images are organized by sets, and we only preload the images corresponding to the 5 current sets with '''ensureSpecificGameImageLoading( image_file_names_array )'''.
<pre>
// By default, do not preload anything
this.dontPreloadImage( 'cards.png' );
this.dontPreloadImage( 'clan1.png' );
this.dontPreloadImage( 'clan2.png' );
this.dontPreloadImage( 'clan3.png' );
this.dontPreloadImage( 'clan4.png' );
this.dontPreloadImage( 'clan5.png' );
this.dontPreloadImage( 'clan6.png' );
this.dontPreloadImage( 'clan7.png' );
this.dontPreloadImage( 'clan8.png' );
this.dontPreloadImage( 'clan9.png' );
this.dontPreloadImage( 'clan10.png' );
var to_preload = [];
for( i in this.gamedatas.clans )
{
var clan_id = this.gamedatas.clans[i];
to_preload.push( 'clan'+clan_id+'.png' );
}

this.ensureSpecificGameImageLoading( to_preload );

</pre>

'''Note:''' You don't need to specify to not preload game box images (game_box.png, game_box75.png...) since they are not preloaded by default.

'''this.ensureSpecificGameImageLoading(list: string[])'''

This is oppostive of dontPreloadImage - its ensure specific images is loaded. Note: only makes sense if preload list is empty, otherwise everything is loaded anyway

'''load specific images'''
All images that will be preloaded stored in g_img_preload. If you want to override it directly - there is no API, but you can do this in GAME constructor

g_img_preload = ['tokens.png', 'trains.png', 'loc_plan.png', 'eng.png', 'eng-back.png'];

You can also set it to empty array and call ensureSpecificGameImageLoading() on specific images

== Sounds ==

Add a custom sound and make it load with your interface:

Add this in your template (.tpl) file:
<pre>
<audio id="audiosrc_<gamename>_<yoursoundname>" src="{GAMETHEMEURL}img/<gamename>_<yoursoundname>.mp3" preload="none" autobuffer></audio>
<audio id="audiosrc_o_<gamename>_<yoursoundname>" src="{GAMETHEMEURL}img/<gamename>_<yoursoundname>.ogg" preload="none" autobuffer></audio>
</pre>

Note: this is a requirement to provide both a mp3 and a ogg file with the names <code><gamename>_<yoursoundname>[.ogg][.mp3]</code>.

Play the sound (from your .js file):

<pre>
playSound('<gamename>_<yoursoundname>'); // do not add 'this.' - its a global function
</pre>

Disable the standard "move" sound for this move (to replace it with your custom sound):

Add this to your notification handler:

<pre>
this.disableNextMoveSound();
</pre>

Note: it only disable the sound for the next move.

== Title bar and states ==

=== Client states ===

Client states is a way to simulate the state transition but without actually going
to server. It is usefull when you need to ask user multiple questions before you
send things to server

'''this.setClientState(newState: string, args: object)'''

Example:
this.setClientState("client_playerPicksLocation", {
descriptionmyturn : _("${you} must select location"),
});

For more information see [[BGA_Studio_Cookbook#Multi_Step_Interactions:_Select_Worker.2FPlace_Worker_-_Using_Client_States]]

'''this.restoreServerGameState()'''
If you are in client state it will restore the current server state (cheap undo)

'''this.on_client_state'''
Boolean indicating that we are in client state

=== Title bar ===
If you simply want to show something in title bar you can do it directly
$('pagemaintitletext').innerHTML = text;

This however will not work with parameters and will not draw You in color,
if you want to do proper args rendering use method below

;'''this.removeActionButtons()'''
Removes all buttons from title bar

;'''this.updatePageTitle()'''
:This function allows to update the current page title and turn description according to the game state arguments. If the current game state description this.gamedatas.gamestate.descriptionmyturn is modified before calling this function it allows to update the turn description without changing state. This will handle arguments substitutions properly.

Note: this functional also will calls this.onUpdateActionButtons, if you want different buttons then state defaults, use method in example to replace them, if it becomes too clumsy use client states (see above)

Example from Terra Mystica:
<pre>
onClickFavorTile: function( evt ) {
...
if ( ... ) {
this.gamedatas.gamestate.descriptionmyturn = _('Special action: ') + _('Advance 1 space on a Cult track');
this.updatePageTitle();
this.removeActionButtons();
this.addActionButton( ... );
...
return;
}
...

}
</pre>

== User preferences ==
'''this.getGameUserPreference(pref_id)'''

Return the value of a user preference. It will return the value currently selected in the select combo box, in the top-right menu.

'''this.setGameUserPreference(pref_id, value)'''

Programmatically change a user preference. It will have the same effect as if the player changed the value in the select combo box, in the top-right menu.

'''this.onGameUserPreferenceChanged'''

A callback you can define if you want to be notified when a user changes a user preference.

Example:<pre>
onGameUserPreferenceChanged: function(pref_id, pref_value) {
switch (pref_id) {
case 201:
document.getElementsByTagName('html')[0].classList.toggle('dark-background', pref_value == 2);
break;
}
}
</pre>

== Other useful stuff ==

'''dojo.hitch'''

With dojo.hitch, you can create a callback function that will run with your game object context whatever happen.

Typical example: display a BGA confirmation dialog with a callback function created with dojo.hitch:

<pre>
this.confirmationDialog( _('Are you sure you want to make this?'), dojo.hitch( this, function() {
this.bgaPerformAction('makeThis');
} ) );
</pre>

In the example above, using dojo.hitch, we ensure that the "this" object will be set when the callback is called.

NOTE: In modern JS there are lambdas that eliminate need for that, the example above will look like this
<pre>
this.confirmationDialog( _('Are you sure you want to make this?'), () => this.bgaPerformAction( 'makeThis') );
</pre>

;'''onScreenWidthChange()'''
:This function can be overridden in your game to manage some resizing on the client side when the browser window is resized. This function is also triggered at load time, so it can be used to adapt to the :viewport size at the start of the game too.

; this.bRealtime
: Return true if the game is in realtime. Note that having a distinct behavior in realtime and turn-based should be exceptional.

; g_replayFrom
: Global contains replay number in live game, it is set to undefined (i.e. not set) when it is not a replay mode, so consequentially the good check is '''typeof g_replayFrom != 'undefined'''' which returns true if the game is in replay mode <i>during the game</i> (the game is ongoing but the user clicked "replay from this move" in the log)

; g_archive_mode
: Returns true if the game is in archive mode <i>after the game</i> (the game has ended)

; this.instantaneousMode
: Returns true during replay/archive mode if animations should be skipped. Only needed if you are doing custom animations. (The BGA-provided animation functions like <i>this.slideToObject()</i> automatically handle instantaneous mode.)
: Technically, when you click "replay from move #20", the system replays the game from the very beginning with moves 0 - 19 happening in instantaneous mode and moves 20+ happening in normal mode.

; g_tutorialwritten
: Returns an object like the below if the game is in tutorial mode, or undefined otherwise. Tutorial mode is a special case of archive mode where comments have been added to a previous game to teach new players the rules.
{
author: "91577332",
id: "576",
mode: "view"
status: "alpha"
version_override: null
viewer_id: "84554161"
}

'''getBgaEnvironment(): string'''
: Returns "studio" for studio and "prod" for production environment (i.e. where games current runs). Only useful for debbugging hooks.
Note: alpha server is also "prod"

[[Category:Studio]]

Game interface logic: Game.js

2024-09-23T10:01:00Z

Sguzzer Gunayer: /* Style */

{{Studio_Framework_Navigation}}

__TOC__

This is the main file for your game interface. Here you will define:

* Which actions on the page will generate calls to the server.
* What happens when you get a notification for a change from the server and how it will show in the browser.
* Setup user interface

== File structure ==

The details of how the file is structured are described below with comments in the code skeleton provided to you.

Here is the basic structure:

* '''constructor''': here you can define global variables for your whole interface.
* '''setup''': this method is called when the page is refreshed, and sets up the game interface.
* '''onEnteringState''': this method is called when entering a new game state. You can use it to customize the view for each game state.
* '''onLeavingState''': this method is called when leaving a game state.
* '''onUpdateActionButtons''': called on state changes, in order to add action buttons to the status bar. Note: in a multipleactiveplayer state, it will be called when another player has become inactive.
* ''(utility methods)'': this is where you can define your utility methods.
* ''(player's actions)'': this is where you can write your handlers for player actions on the interface (example: click on an item).
* '''setupNotifications''': this method associates notifications with notification handlers. For each game notification, you can trigger a javascript method to handle it and update the game interface.
* ''(notification handlers)'': this is where you define the notifications handlers associated with notifications in '''setupNotifications''', above.

More details:

'''setup(gamedatas: object) '''
This method must set up the game user interface according to current game situation specified in parameters.
The method is called each time the game interface is displayed to a player, ie:

* when the game starts
* when a player opens a game in the browser later
* when a player refreshes the game page (F5)
* when player does a server side Undo

"gamedatas" argument contains all data retrieved by your "getAllDatas" PHP method and some more.

'''onEnteringState(stateName: string, args: { args: any } | null): void'''

This method is called each time we enter a new game state.
You can use this method to perform some user interface changes at this moment.
To access state arguments passed via calling php arg* method use args?.args.
Typically you would do something only for active player, using this.isCurrentPlayerActive() check.
It is also called (for the current game state only) when doing a browser refresh (after the setup method is called).

'''Warning''': for multipleactiveplayer states:
the active players are NOT active yet so you must use onUpdateActionButtons to perform the client side operation which depends on a player active/inactive status.
If you are doing initialization of some structures which do not depend on the active player, you can just replace (this.isCurrentPlayerActive()) with (!this.isSpectator)
for the main switch in that method.

See more details in [[Your_game_state_machine:_states.inc.php#Difference_between_Single_active_and_Multi_active_states]]

'''onLeavingState(stateName: string): void'''

This method is called each time we leave a game state.
You can use this method to perform some user interface changes at this point (i.e. cleanup).

'''onUpdateActionButtons(stateName: string, args: object | null): void'''

In this method you can manage "action buttons" that are displayed in the action status bar and highlight active UI elements.
To access state arguments passed via calling php arg* method use '''args''' parameter. Note: args can be null! For '''game''' states and when you don't supply state args function - it is null.
This method is called when the active or multiactive player changes. In a classic "activePlayer" state this method is called before the onEnteringState state.
In multipleactiveplayer state it is a mess. The sequencing of calls depends on whether you get into that state from transitions OR from reloading the whole game (i.e. F5).

See more details in [[Your_game_state_machine:_states.inc.php#Difference_between_Single_active_and_Multi_active_states]]

== Dojo framework ==

BGA uses the [http://dojotoolkit.org/ Dojo Javascript framework].

The Dojo framework allows us to do complex things more easily. The BGA framework uses Dojo extensively.

To implement a game, you only need to use a few parts of the Dojo framework. All the Dojo methods you need are described on this page.

== Javascript minimization (after July 2020) ==

For performance reasons, when deploying a game the javascript code is minimized using '''terser''' (https://github.com/terser/terser). This minifier works with modern javascript syntax. From your project "Manage game" page, you can now test a minified version of your javascript on the studio (and revert to the original).

NB: it has been reported that there is an issue with this minifier and percentage values for opacity.

== Accessing Players Information ==

'''this.player_id: number'''
id of the player who is looking at the game. The player may not be part of the game (i.e. spectator)
if (notif.args.player_id == this.player_id) {
...
}

'''this.isSpectator: boolean'''
Flag set to true if the user at the table is a spectator (not a player).

Example:
<pre>
if (this.isSpectator) {
this.player_color = 'ffffff';
} else {
this.player_color = gamedatas.players[this.player_id].color;
}
</pre>

Note: If you want to hide an element from spectators, you should use [[Game_interface_stylesheet:_yourgamename.css#spectatorMode|CSS 'spectatorMode' class]].

You may consider making a function like this, to detect if the game is in a read-only state (i.e. non-interactive):
// Returns true for spectators, instant replay (during game), archive mode (after game end)
isReadOnly: function () {
return this.isSpectator || typeof g_replayFrom != 'undefined' || g_archive_mode;
}

'''this.gamedatas: object'''
Contains the initial set of data to init the game, created at game start or by game refresh (F5).
You can update it as needed to keep an up-to-date reference of the game on the client side if you need it, however most of the time this is unnecessary.

Note: In hotseat mode, the framework does not keep this.gamedatas of hotseat players and shares the same set as the main player to store data.

Note: be careful when you update this data structurally, many framework functions expect data to be certain way and they will break if they see something else.

Typical example of accessing player's info
<pre>
for (var player_id in this.gamedatas.players) {
var playerInfo = this.gamedatas.players [player_id];
var c = playerInfo.color;
var name = playerInfo.name;
// do something
}
</pre>

'''this.isCurrentPlayerActive(): boolean'''
Returns true if the player on whose browser the code is running is currently active (it's his turn to play). Note: see remarks above about usage of this function inside onEnteringState method.
if (this.isCurrentPlayerActive()) {

'''this.getActivePlayerId(): number'''
Return the ID of the active player, or null if we are not in an "activeplayer" type state.
if (this.player_id == this.getActivePlayerId()) ...

'''this.getActivePlayers(): number[]'''
Return an array with the IDs of players who are currently active (or an empty array if there are none).

== Accessing and manipulating the DOM ==

=== Element by Id ===

'''$(elementId: ElementOrId)'''

The $ function is used to get an HTML element using its "id" attribute.

Example: modify the content of a "span" element:

<pre>
In your HTML code:
<span id="a_value_in_the_game_interface">1234</span>

In your Javascript code:
$('a_value_in_the_game_interface').innerHTML = "9999";
</pre>

Note: It is safe to use if you don't know if variable is string (id of element) or element itself, i.e.
<pre>
foo: function(card) {
card = $(card); // now its node, no need to write if (typeof card === 'string') ...
// but its good idea to check for null here
...
}
</pre>

'''getElementById(elementId: string)'''

Note: $() is the standard method to access some HTML element with the BGA Framework. You can use '''getElementById''' but a longer to type and less handy as it does not do some checks.

=== Style ===

'''dojo.style(node: ElementOrId, styleName: string, styleValue: any): void'''

With dojo.style you can modify the CSS property of any HTML element in your interface.

Examples:

<pre>
// Make an element disappear
dojo.style( 'my_element', 'display', 'none' );

// Give an element a 2px border
dojo.style( 'my_element', 'borderWidth', '2px' );

// Change the background position of an element
// (very practical when you are using CSS sprites to transform an element to another)
dojo.style( 'my_element', 'backgroundPosition', '-20px -50px' );
</pre>

Note: if you have to modify several CSS properties of an element, or if you have a complex CSS transformation to do, you should consider using dojo.addClass/dojo.removeClass (see below).

You can also use object to set multiple values
<pre>
dojo.setStyle("thinger", {
"opacity": 0.5,
"border": "3px solid black",
"height": "300px"
});
</pre>

'''this.addStyleToClass(cssClassName: string, styleName: string, styleValue: any):''' '''void'''

Same as dojo.style(), but for all the nodes set with the specified cssClassName
Equivalent of

dojo.query(`.${aclass}`).style(styleName, styleValue)

<pre>
dojo.query("#baz > div").style({
opacity:0.75,
fontSize:"13pt"
});
</pre>

'''Vanilla JS style'''
$('my_element').style.display='none'; // set
var display = $('my_element').style.display; // get
$('my_element').style.removeProperty('display'); // remove

=== Classes ===

'''dojo.addClass(node: ElementOrId, classes: string): void'''

'''dojo.removeClass(node: ElementOrId, classes: string): void'''

'''dojo.hasClass(node: ElementOrId, aclass: string): void'''

'''dojo.toggleClass(node: ElementOrId, aclass: string): void'''

In many situations, many small CSS property updates can be replaced by a CSS class change (i.e., you add a CSS class to your element instead of applying all modifications manually).

Advantages are:
* All your CSS stuff remains in your CSS file.
* You can add/remove a list of CSS modifications with a simple function and without error.
* You can test whether you applied the CSS to an element with the '''dojo.hasClass''' method.

Example from ''Reversi'':

<pre>
// We add "possibleMove" to an element
dojo.addClass( 'square_'+x+'_'+y, 'possibleMove' );

// In our CSS file, the class is defined as:
.possibleMove {
background-color: white;
opacity: 0.2;
filter:alpha(opacity=20); /* For IE8 and earlier */
cursor: pointer;
}

// So we've applied 4 CSS property changes in one line of code.

// ... and when we need to check if a square is a possible move on the client side:
if( dojo.hasClass( 'square_'+x+'_'+y, 'possibleMove' ) )
{ ... }

// ... and if we want to remove all possible moves in one line of code (see "dojo.query" method):
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );
</pre>

'''Vanila JS classList'''

This is the only exception where dojo versions are better
// add class
$(token_id).classList.addClass('possibleMove');
// remove class
$(token_id).classList.removeClass('possibleMove');
// add 2 classes
const myclasses = ['a','b'];
$(token_id).classList.addClass(...myclasses);
// add classes to query result
document.querySelectorAll(".hand .card").forEach((node)=>node.classList.addClass('possibleMove'));

=== Attributes ===

;dojo.attr

With dojo.attr you can access or change the value of an attribute or property of any HTML element in your interface.

Exemple:
<pre>
// Get the title of a node
var title = dojo.attr( id, 'title' );
// Change the height of a node
dojo.attr( 'img_growing_tree', 'height', 100 );
</pre>

'''Vanila JS attr'''

$(token).id=new_id; // set attr for "id"
var id = $(token).id; // get

=== Queries ===

'''dojo.query(cssSelector: string): Element[]'''

With dojo.query, you can query a bunch of HTML elements with a single function, with a "CSS selector" style.

Example:
<pre>
// All elements with class "possibleMove":
var elements = dojo.query( '.possibleMove' );

// Count number of tokens (i.e., elements of class "token") on the board (i.e., the element with id "board"):
dojo.query( '#board .token' ).length;
</pre>

But what is really cool with dojo.query is that you can combine it with almost all methods above.

Examples:
<pre>
// Trigger a method when the mouse enter in any element with class "meeple":
dojo.query( '.meeple' ).connect( 'onmouseenter', this, 'myMethodToTrigger' );

// Hide all meeples who are on the board
dojo.query( '#board .meeple' ).style( 'display', 'none' );
</pre>

'''Vanila JS query'''

var cards=document.querySelectorAll(".hand .card");// all cards in all hands
var cards=$('hand').querySelectorAll(".card");// all cards in specific hand
var card=document.querySelector(".hand .card");// first card or null if none (super handy)

=== Creating and Destroying elements ===

'''dojo.empty(node: ElementOrId)'''

Remove all children of the node element
dojo.empty('my_hand');

'''dojo.destroy(node: ElementOrId)'''

Remove the element
dojo.destroy('my_token');

dojo.query(".green", mynode).forEach(dojo.destroy); // this remove all subnode of class green from mynode

'''dojo.create(tag: string, attributes?: obj, parent?: ElementOrId): Element'''

Create element

dojo.create("div", { class: "yellow_arrow" }, parent); // this creates div with class yellow_array and places it in "parent"

'''this.format_block(name: string, args: object): string'''
This bga function that takes global var from template file and substitute variables, typical use would be

var player = gamedatas.players[player_id];
var div = this.format_block('jstpl_player_board', player ); // var jstpl_player_board = ... is defined in .tpl file
Note: result is trimmed

'''this.format_string(name: string, args: object): string'''
This bga function just substitute variables in a string, i.e.
<pre>
var div = this.format_string('<div color="${player_color}"></div>', {player_color: '#ff0000'} );
</pre>
Note: result is trimmed

Note: this can be replaced by using backquoted string now:
const player_color = '#ff0000';
const div = `<div color="${player_color}"></div>`;

'''this.format_string_recursive'''
This bga function is similar to this.format_string but is capable of processing recursive argument structures and translations. It is used to format server notifications.

TODO: find better place for these function docs

=== Moving elements ===

'''dojo.place(node: string | Element, refNode: ElementOrId, pos?: string | number): Element'''

dojo.place is the best function to insert HTML code somewhere in your game interface without breaking something. It is much better to use than the '''innerHTML=''' method if you must insert HTML tags and not only values.

node:

Can be a String or a DOM node. If it is a string starting with “<”, it is assumed to be an HTML fragment, which will be created. Otherwise it is assumed to be an id of a DOM node.

<pre>
// Insert your HTML code as a child of a container element
dojo.place( "<div class='foo'></div>", "your_container_element_id" );
</pre>

pos:

Optional argument. Can be a number or one of the following strings: “before”, “after”, “replace”, “only”, “first”, or “last”. If omitted, “last” is assumed.

"replace": Replace the container element with my_node element

"first": Places the node as a child of the reference node. The node is placed as the first child.

"last" (default): Places the node as a child of the reference node. The node is placed as the last child.

"before": places the node right before the reference node.

"after": places the node right after the reference node.

"only": replaces all children of the reference node with the node.

positive integer: This parameter can be a positive integer. In this case, the node will be placed as a child of the reference node with this number (counting from 0). If the number is more than number of children, the node will be appended to the reference node making it the last child.

<pre>
// Replace all children of container with my_node
dojo.place( $('my_node'), "your_container_element_id", "only" );
</pre>

See also full doc on dojo.place: [https://dojotoolkit.org/reference-guide/1.7/dojo/place.html]

Usually, when you want to insert some piece of HTML in your game interface, you should use "[[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl#Javascript_templates|Javascript templates]]".

But you can also relocate elements like that. Note: it won't animate if you do that.

'''this.placeOnObject(mobile_obj: ElementOrId, target_obj: ElementOrId): void'''

places mobile_obj on target_obj, set the absolute positions and centers the mobile_obj on target_obj,
effect is immediate

This is not really an animation, but placeOnObject is frequently used before starting an animation.

Example:
<pre>
// (We just created an object "my_new_token")

// Place the new token on current player board
this.placeOnObject( "my_new_token", "overall_player_board_"+this.player_id );

// Then slide it to its position on the board
this.slideToObject( "my_new_token", "a_place_on_board" ).play();
</pre>

'''this.placeOnObjectPos(mobile_obj: ElementOrId, target_obj: ElementOrId, target_x: number, target_y: number): void'''

This method works exactly like placeOnObject, except than you can specify some (x,y) coordinates (in px). This way, the center of "mobile_obj" will be placed to the specified x,y position relatively to the center of "target_obj".

''Note: the placement works differently from this.slideToObjectPos'', since coordinates are calculated based on the center of objects.

'''this.attachToNewParent(mobile_obj: ElementOrId, target_obj: ElementOrId): void'''

With this method, you change the HTML parent of "mobile_obj" element without moving it.
"target_obj" is the new parent of this element. The beauty of
attachToNewParent is that the mobile_obj element DOES NOT MOVE during this process.

What happens is that the method calculate a relative position of mobile_obj to make sure it does not move after the HTML parent changes.

Why using this method?

Changing the HTML parent of an element can be useful for the following reasons:
* When the HTML parent moves, all its child are moving with them. If some game elements is no more linked with a parent HTML object, you may want to attach it to another place.
* The z_order (vertical order of display) depends on the position in the DOM, so you may need to change the parent of some game elements when they are moving in your game area.

'''CAREFUL''': this function destroys original object and places a clone onto a new parent, this will break all references to this HTML element (ex: dojo.connect).
If you need version that does not destroy the object but the same otherwise see [[BGA_Studio_Cookbook#Attach_to_new_parent_without_destroying_the_object]]

== Animations ==

===Dojo Animations===

BGA animations is based on Dojo Animation ([http://dojotoolkit.org/documentation/tutorials/1.8/animation/ see tutorial here]).

However, most of the time, you can just use methods below, which are built on top of Dojo Animation.

Note: one interesting method from Dojo that could be useful from time to time is "Dojo.Animation". It allows you to make any CSS property "slide" from one value to another.

Note 2: the slideTo methods are not compatible with CSS transform (scale, zoom, rotate...). If possible, avoid using CSS transform on nodes that are being slided. Eventually, the only possible solution to make these 2 compatible is to disable all CSS transform properties, use slideToObjectPos/placeOnObjectPos, and then apply them again.

===Sliding===

'''this.slideToObject(mobile_obj: ElementOrId, target_obj: ElementOrId, duration?: number, delay?: number): Animation'''

You can use slideToObject to "slide" an element to a target position.

Sliding element on the game area is the recommended and the most used way to animate your game interface. Using slides allow players to figure out what is happening on the game, as if they were playing with the real boardgame.

The parameters are:
* mobile_obj: the ID of the object to move. This object must be "relative" or "absolute" positioned.
* target_obj: the ID of the target object. This object must be "relative" or "absolute" positioned. Note that it is not mandatory that mobile_obj and target_obj have the same size. If their size are different, the system slides the center of mobile_obj to the center of target_obj.
* duration: (optional) defines the duration in millisecond of the slide. The default is 500 milliseconds.
* delay: (optional). If you defines a delay, the slide will start only after this delay. This is particularly useful when you want to slide several object from the same position to the same position: you can give a 0ms delay to the first object, a 100ms delay to the second one, a 200ms delay to the third one, ... this way they won't be superposed during the slide.

BE CAREFUL: The method returns an dojo.fx animation, so you can combine it with other animation if you want to. It means that you have to call the "play()" method, otherwise the animation WON'T START.

Example:
<pre>
this.slideToObject( "some_token", "some_place_on_board" ).play();
</pre>

'''this.slideToObjectPos(mobile_obj: ElementOrId, target_obj: ElementOrId, target_x: number, target_y: number, duration?: number, delay?: number): Animation'''

This method does exactly the same as "slideToObject", except than you can specify some (x,y) coordinates. This way, "mobile_obj" will slide to the specified x,y position relatively to "target_obj".

Example: slide a token to some place on the board, 10 pixels from the top:
<pre>
this.slideToObjectPos( "some_token", "some_place_on_board", 0, 10 ).play();
</pre>

'''this.slideTemporaryObject(mobile_obj_html: string, parent: ElementOrId, from: ElementOrId, to: ElementOrId, duration?: number, delay?: number): Animation'''

This method is useful when you want to slide a temporary HTML object from one place to another. As this object does not exists before the animation and won't remain after, it could be complex to create this object (with dojo.place), to place it at its origin (with placeOnObject) to slide it (with slideToObject) and to make it disappear at the end.

slideTemporaryObject does all of this for you:
* mobile_obj_html is a piece of HTML code that represent the object to slide.
* parent is the ID of an HTML element of your interface that will be the parent of this temporary HTML object.
* from is the ID of the origin of the slide.
* to is the ID of the target of the slide.
* duration/delay works exactly like in "slideToObject"

Example:
<pre>
this.slideTemporaryObject( '<div class="token_icon"></div>', 'tokens', 'my_origin_div', 'my_target_div' ).play();
</pre>

===Destroy===
'''this.slideToObjectAndDestroy(mobile_obj: ElementOrId, target_obj: ElementOrId, duration?: number, delay?: number): void'''

This method is a handy shortcut to slide an existing HTML object to some place then destroy it upon arrival. It can be used for example to move a victory token or a card from the board to the player panel to show that the player earns it, then destroy it when we don't need to keep it visible on the player panel.

It works the same as this.slideToObject and takes the same arguments, but it starts the animation.

CAREFUL: Make sure nothing is creating the same object at the same time the animation is running, because this will cause some random disappearing effects

Example:
<pre>
this.slideToObjectAndDestroy( "some_token", "some_place_on_board", 1000, 0 );
</pre>

'''this.fadeOutAndDestroy( node: string | Element, duration?: number, delay?: number):''' '''void'''

This function fade out the target node, then destroy it. Its starts the animation.
* duration/delay works exactly like in "slideToObject"

Example:
<pre>
this.fadeOutAndDestroy( "a_card_that_must_disappear" );
</pre>

CAREFUL: the HTML node still exists until during few milliseconds, until the fadeOut has been completed.
Make sure nothing is creating same object at the same time as animation is running, because you will be some random dissapearing effects

===Rotating elements===

This example combines "Dojo.Animation" method and a CSS property transform that allow you to rotate the element.
<pre>
// node is Element we rotating
var animation = new dojo.Animation({
curve: [fromDegree, toDegree],
onAnimate: (v) => {
node.style.transform = 'rotate(' + v + 'deg)';
}
});

animation.play();
</pre>

BGA has its own interface to rotate

'''this.rotateTo(node: string | Element, degree: number): void'''

It starts the animation, and stored the rotation degree in the class, so next time you rotate object - it is additive.
There is no animation hooks in this one, if you need to change any parameters use dojo animation above.

There is also '''rotateInstantTo''' with same signature which does not animate

===Animation Callbacks===

If you wish to run some code only after an animation has completed you can do this by linking a callback method to 'onEnd'.

<pre>
var animation_id = this.slideToObject( mobile_obj, target_obj, 500 );
dojo.connect(animation_id, 'onEnd', () => {
// do something here
});
animation_id.play();
</pre>

If you wish to call a second animation after the first (rather than general code) then you can use a dojo animation chain (see tutorial referenced above).

== Players input ==

=== Connecting ===
'''dojo.connect(element: Element, event: string, context: object, method: eventHandler): any'''

'''dojo.connect(element: Element, event: string, hander: eventHandler): any'''

Used to associate a player event with one of your notification methods.

Example: associate a click on an element ("my_element") with one of our methods ("onClickOnMyElement"):
<pre>
dojo.connect( $('my_element'), 'onclick', this, 'onClickOnMyElement' );
</pre>

Same idea but base on query (i.e. all element of 'pet' class)
dojo.query(".pet").connect('onclick', this, 'onPet');

Note: if you need to disconnect the handler you have to store handler returned from this method, i.e.

<pre>
var handler = dojo.connect(...);
...
dojo.disconnect(handler);
</pre>

If you don't store the handler - you have to destroy the object to disconnect it

Typical function that implements the input handler will look like this

<pre>
onPet: function(event) {
var id = event.currentTarget.id;
console.log('onPet ' + id);
dojo.stopEvent(event);
if (this.gamedatas.gamestate.name == 'playerTurnPet') {
this.bgaPerformAction('actPlayPet', {card: id});
} else {
this.showMoveUnauthorized();
}
}
</pre>

'''this.connect(element: ElementOrId, event: string, method: eventHandler): void'''

Used to associate a player event with one of your notification methods.

this.connect( $('my_element'), 'onclick', 'onClickOnMyElement' );

Or you can use an in-place handler

this.connect( $('my_element'), 'onclick', (e) => { console.log('boo'); } );

Note that this function stores the connection handler. That is the only real difference between '''this.connect''' and '''dojo.connect'''. If you plan to destroy the element you connected, you '''must''' call this.disconnect() to prevent memory leaks.
This function is mainly for permanent objects - if you just want to connect the temp object you should probably not use this method but use dojo.connect which won't require any clean-up.

'''this.connectClass(cssClassName: string, event: string, method: eventHandler): void'''

Same as connect(), but for all the nodes set with the specified cssClassName.

this.connectClass('pet', 'onclick', 'onPet');

'''this.disconnect(element: ElementOrId, event: string): void'''

Disconnect event handler (previously registered with this.connect or this.connectClass).

this.disconnect( $('my_element'), 'onclick');

Note: dynamic connect/disconnect is for advanced cases ONLY, you should always connect elements statically if possible, i.e. in setup() method.

'''this.disconnectAll(): void'''

Disconnect all previously registed event handlers (registered via this.connect or this.connectClass)

this.disconnectAll();

=== Actions ===

'''this.bgaPerformAction(action: string, args?: object, options: object = { lock: true, checkAction: true }): Promise<void>'''

Triggers an action on the backend. This is a combination of checkAction and ajaxcall, returning a Promise which resoves when ajaxcall ends.

This method must be used to send a player input to the game server. '''It should not be triggered programmatically''', especially not in loops, in callbacks, in notifications, or in onEnteringState/onUpdateActionButtons/onLeavingState, in order not to create race conditions or break replay game and tutorial features. It should be used only in reaction to a user action in the interface.

* action: name of the action, as it is written in "possibleactions" of the current state.
* args: an object containing the call parameters to send to the action
* options: options to tweak the call with some defaults. Default is <code>{ lock: true, checkAction: true }</code>.

Example of a standard call without args:
this.bgaPerformAction('pass');

Example of a standard call with action args:
this.bgaPerformAction('actPlayCard', { id: this.selectedCardId });

Example of a call without checking action (because player is inactive in a multiactive state):

this.bgaPerformAction('actChangeMind', {}, { checkAction: false });

Example of a call without lock (because of a special action not directly related to the game flow):

this.bgaPerformAction('actSetAutoBid', { alwaysBidUntil: 500 }, { lock: false, checkAction: false });

Example of call with reaction to exception:
this.bgaPerformAction('actPlayCard', { id: this.selectedCardId }).catch(()=>{ this.selectedCardId = undefined; });

Example of call with reaction to success:
this.bgaPerformAction('actPlayCard', { id: this.selectedCardId }).then(()=>{ this.unselectAll(); });

'''this.ajaxcall(url, parameters, obj_callback, callback, callback_anycase?, ajax_method?: string)'''

''Note: bgaPerformAction is a simpler way to use ajax calls, ajaxcall stays in the doc for legacy reasons only and should not be used in new projects.''

Same warning as '''this.bgaPerformAction''' about using on user action only.

* url: the url of the action to perform. For a game, it must be: "/<mygame>/<mygame>/myAction.html"
* parameters: an array of parameter to send to the game server.
** Note that "lock: true" must always be specified in this list of parameters in order the interface can be locked during the server call. Cannot use lock: false - to not lock it has to be undefined.
** Note: Restricted parameter names (please don't use them):
*** "action"
*** "module"
*** "class"
* obj_callback: must be set to "this".
* callback (non-optional but rarely used): a function to trigger when the server returns result and everything went fine (not used, as all data handling is done via notifications).
* callback_anycase: (optional) a function to trigger when the server returns ok OR error. If no error this function is called with parameter value false. If an error occurred, the first parameter will be set to true, the second will contain the error message sent by the PHP back-end, and the third will contain an error code.
* ajax_method: (optional and rarely used) if you need to send large amounts of data (over 2048 bytes), you can set this parameter to 'post' (all lower-case) to send a POST request as opposed to the default GET. This works, but was not officially documented, so only use if you really need to.

Usage:
<pre>
this.ajaxcall( '/mygame/mygame/actMyAction.html', { lock: true,
arg1: myarg1,
arg2: myarg2
}, this, (result)=>{} );
</pre>

'''this.checkAction(action: string, nomessage?: boolean): boolean '''

Check if player can do the specified action by taking into account:
* if interface is locked it will return false and show message "An action is already in progress", unless nomessage set to true
* if player is not active it will return false and show message "This is not your turn", unless nomessage set to true
* if action is not in list in possible actions (defined by "possibleaction" in current game state) it will return false and show "This move is not authorized now" error (unconditionally).
* otherwise returns true
Example:
<pre>
function onClickOnGameElement( evt ) {
if( this.checkAction( "actMyAction" ) ) {
// Do the action
}
}
</pre>

'''this.checkPossibleActions(action: string): boolean'''

* this is independent of the player being active, so can be used instead of this.checkAction(). This is particularly useful for multiplayer states when the player is not active in a 'player may like to change their mind' scenario. Unlike this.checkAction, this function does NOT take interface locking into account

* if action is not in list in possible actions (defined by "possibleaction" in current game state) it will return false and show "This move is not authorized now" error (unconditionally).
* otherwise returns true

function onChangeMyMind( evt ) {
if( this.checkPossibleActions( "actMyAction" ) ) {
// Do the action
}
}

'''this.checkLock(nomessage?: boolean): boolean'''

When using "lock: true" in ajax call you can use this function to check if interface is in lock state (it will be locked during server call and notification processing).
This check can be used to block some other interactions which do not result in ajaxcall or if you want to suppress errors. Note: normally you only need to use this.checkAction(...), this is for advanced cases.

It will also show error unless nomessage is set to true

function onChangeMyMind( evt ) {
if( this.checkLock() ) {
// Do the action
}
}

== Notifications ==

When something happens on the server side, your game interface Javascript logic received a notification.
If you have not done so yet check what notification are in [[Main_game_logic:_yourgamename.game.php#Notifications]]

Here's how you can handle these notifications on the client side.

=== Subscribe to notifications ===

'''dojo.subscribe(notif_type: string, callback_obj: Object, handler: string|handler)'''
* notif_type - notification type/name send by php server
* callback_obj - usually this
* handler - if string method of callback_obj with name name is called, when notification is called, with notification object as parameter (see below)

Your Javascript "setupNotifications" method is the place where you can subscribe to notifications from your PHP code.

Here's how you associate one of your Javascript method to a notification "playDisc" (from Reversi example):

<pre>
setupNotifications: function() {
...
dojo.subscribe('playDisc', this, "notif_playDisc");
},
</pre>

Note: the "playDisc" corresponds to the name of the notification you define it in your PHP code, in your "notifyAllPlayers" or "notifyPlayer" method.

Then, you have to define your "notif_playDisc" method:

<pre>
notif_playDisc: function(notif) {
// Remove current possible moves (makes the board more clear)
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );
this.addDiscOnBoard( notif.args.x, notif.args.y, notif.args.player_id );
},
</pre>

In a notification handler like our "notif_playDisc" method, you can access all notifications arguments with "notif.args".

Example:

PHP

<pre>
$this->notifyAllPlayers( "apples", clienttranslate('player takes ${count} apples'), [ "count" => 3 ] );
</pre>

JavaScript

<pre>
setupNotifications: function() {
dojo.subscribe( 'apples', this, 'notif_apples' );
},

notif_apples: function(notif) {
//You can access the "count" like this:
alert("count = " + notif.args.count);
}
</pre>

=== The notification Object received by client ===

When sending a notification on your PHP, the client side will receive an Object with the following attributes:

* type - type of the notification (as passed by php function)
* log - the log string passed from php notification
* args - This is the arguments that you passed on your notification method on php
* bIsTableMsg - is true when you use [[Main_game_logic:_yourgamename.game.php#NotifyAllPlayers|NotifyAllPlayers]] method (false otherwise)
* channelorig - information about table ID (formatted as : "/table/t[TABLE_NUMBER]")
* gamenameorig - name of the game
* move_id - ID of the move associated with the notification
* table_id - ID of the table (comes as string)
* time - UNIX GMT timestamp
* uid - unique identifier of the notification
* h - unknown

'' Note that those information were inferred from observation on console log. If an Admin can confirm/correct (and remove this line), you're welcome :)''

=== Ignoring notifications ===

Sometimes you need to ignore some notification on client side. You don't want them to be shown in game log and you don't want them to be handled.

The most common use case is when a player gets private information. They will receive a specific notification (such as "You received Ace of Heart"), while other players would receive more generic notification ("Player received a card").

In X.game.php
<pre>
$this->notifyAllPlayers("dealCard", clienttranslate('${player_name} received a card'), [
'player_id' => $playerId,
'player_name' => $this->getActivePlayerName()
]);

$this->notifyPlayer($playerId, "dealCardPrivate", clienttranslate('You received ${cardName}'), [
"type" => $card["type"],
"cardName" => $this->getCardName($card["type"])
]);
</pre>

The problem with this approach is that the active player will receive two notifications:
* Player1 received a card
* You received Ace of Hearts

Hence, notification ignoring.

NOTE: You can think that it would be possible to send such notification to all players except active just by using notifyPlayer and it seems to work. The problem however is that table spectators would miss such notification and their user interface (and game log) wouldn't be updated. Since there is no way to send notification just to spectators, ignoring the notification (or "filtering") is the only reasonable solution.

'''setIgnoreNotificationCheck(notif_type: string, predicate: ((notif: Notif)=>boolean))'''
This method will set a check whether any of notifications of specific type should be ignored.

The parameters are:
* notif_type: type of the notification
* predicate (notif => boolean): a function that will receive notif object and will return true if this specific notification should be ignored

Before dispatching any notification of this type, the framework will call predicate to check whether notification should be ignored, if it return true - the notification will be dispatched, i.e. logged or handled.

<pre>
this.notifqueue.setIgnoreNotificationCheck( 'dealCard', (notif) => (notif.args.player_id == this.player_id) );
</pre>

IMPORTANT: Remember that this notification is ignored on the client side, but was still received by the client. Therefore it shouldn't contain any private information as cheaters can get it. In other words this is not a way to hide information.

IMPORTANT: When a game is reloaded with F5 or when opening a turn based game, old notifications are replayed as history notification. They are used just to update the game log and are stripped of all arguments except player_id, i18n and any argument present in message. If you use and other argument in your predicate you should '''preserve''' it as explained [[Main_game_logic:_yourgamename.game.php#Notify_players|here]].

=== Synchronous notifications ===

When several notifications are received by your game interface, these notifications are processed immediately, one after the other, in the same exact order they have been generated in your PHP game logic.

However, sometimes, you need to give some time to the players to figure out what happened on the game before jumping to the next notification. Indeed, in many games, there are a lot of automatic actions, and the computer is going to resolve all these actions very fast if you don't tell it not to do so.

As an example, for Reversi, when someone is playing a disc, we want to wait 500 milliseconds before doing anything else in order the opponent player can figure out what move has been played.

Here's how we do this, right after our subscription:
<pre>
dojo.subscribe( 'playDisc', this, "notif_playDisc" );
this.notifqueue.setSynchronous( 'playDisc', 500 ); // Wait 500 milliseconds after executing the playDisc handler
</pre>

-----

It is also possible to control the delay timing dynamically (e.g., using notification args). As an example, maybe your notification 'cardPlayed' should pause for a different amount of time depending on the number or type of cards played.

For this case, use '''setSynchronous''' without specifying the duration and use '''setSynchronousDuration''' within the notification callback.

* NOTE: If you forget to invoke '''setSynchronousDuration''', the game will remain paused forever!

<pre>
setupNotifications: function () {
dojo.subscribe( 'cardPlayed', this, 'notif_cardPlayed' );
this.notifqueue.setSynchronous( 'cardPlayed' ); // wait time is dynamic
...
},

notif_cardPlayed: function (notif) {
// MUST call setSynchronousDuration

// Example 1: From notification args (PHP)
this.notifqueue.setSynchronousDuration(notif.args.duration);
...

// Or, example 2: Match the duration to a Dojo animation
var anim = dojo.fx.combine([
...
]);
anim.play();
this.notifqueue.setSynchronousDuration(anim.duration);
},
</pre>

You can also manually call this.notifqueue.setSynchronousDuration(0) once client operations are finished, but be careful that even fast replay still has a path to call it.

'''WARNING: combining synchronous and ignored notifications'''
You must be careful when combining dynamic synchronous durations (as described above) with ignored notifications. If you have a conditionally ignored notification like this (see below section):

<pre>this.notifqueue.setIgnoreNotificationCheck( 'myNotif', (notif) => (notif.args.player_id == this.player_id) /* or any other condition */ )</pre>

then you CANNOT do

<pre>this.notifqueue.setSynchronous('myNotif');</pre>

as, when the ignored check passes, the notification handler, in which `this.notifqueue.setSychronousDuration` is called, is never called and so the duration is never set and interface locking results.

The workaround is to set a "dummy" time:

<pre>this.notifqueue.setSynchronous('myNotif', 5000);</pre>

whose value is irrelevant but must be large enough to cover the time before the notification handler is called. The large value never actually comes into play because the notification is either ignored, or the synchronous duration is reset to a sensible value inside the handler.

=== Pre-defined notification types ===

'''tableWindow''' - This defines notification to display [[Game_interface_logic:_yourgamename.js#Scoring_dialogs|Scoring Dialogs]], see below.

'''message''' - This defines notification that shows on players log and have no other effect (technically any unhandled notification will do the same but its recommended to use this keyword for consistency)

// You can call this on php side without doing anything on client side
self::notifyAllPlayers( 'message', clienttranslate('hello'), [] );

'''simplePause''' - This notification will just delay other notifications, maybe useful if you know you need some extra time for animation or something. Requires a time parameter.

<pre>
self::notifyAllPlayers( 'simplePause', '', [ 'time' => 500] ); // time is in milliseconds
</pre>

Note: the following types are RESERVED by framework, do not use:

gameStateChange gameStateChangePrivateArg gameStateMultipleActiveUpdate newActivePlayer playerstatus yourturnack clockalert tableInfosChanged playerEliminated tableDecision archivewaitingdelay end_archivewaitingdelay replaywaitingdelay end_replaywaitingdelay replayinitialwaitingdelay end_replayinitialwaitingdelay aiPlayerWaitingDelay replay_has_ended updateSpectatorList wouldlikethink updateReflexionTime undoRestorePoint resetInterfaceWithAllDatas zombieModeFail zombieModeFailWarning aiError skipTurnOfPlayer zombieBack allPlayersAreZombie gameResultNeutralized playerConcedeGame showTutorial showCursor showCursorClick skipTurnOfPlayerWarning banFromTable resultsAvailable switchToTurnbased newPrivateState infomsg

== Tooltips ==

=== Adding static tooltips ===

'''this.addTooltip(nodeId: string, helpStringTranslated: string, actionStringTranslated: string, delay?: number): void'''

Add a simple text tooltip to the DOM node.

Specify 'helpStringTranslated' to display some information about "what is this game element?".
Specify 'actionStringTranslated' to display some information about "what happens when I click on this element?".

You must specify both of the strings. You can only use one and specify an empty string ('') for the other one.

When you pass text directly function _() must be used for the text to be marked for translation! Except for empty string.

Parameter "delay" is optional. It is primarily used to specify a zero delay for some game element when the tooltip gives really important information for the game - but remember: no essential information must be placed in tooltips as they won't be displayed in some browsers (see [[BGA_Studio_Guidelines|Guidelines]]).

Example:
<pre>
this.addTooltip( 'cardcount', _('Number of cards in hand'), '' );
</pre>

Note: this generates static tooltip and attaches to existing dom element, if you need to generate tooltip more dynamically you have to call that method every time information about object is updated or use completely different tehnique, see dynamic tooltips below.

'''this.addTooltipHtml(nodeId: string, html: string, delay?: number): void'''

Add an HTML tooltip to the DOM node (for more elaborate content such as presenting a bigger version of a card).

'''this.addTooltipToClass(cssClass: string, helpStringTranslated: string, actionStringTranslated: string, delay?: number ): void'''

Add a simple text tooltip to all the DOM nodes set with this cssClass. See more details above for this.addTooltip.
this.addTooltipToClass( 'meeple', _('This is A Meeple'), _('Click to tickle') );

IMPORTANT: all concerned nodes must exist and have IDs to get tooltips.

'''this.addTooltipHtmlToClass(cssClass: string, html: string, delay?: number): void'''

Add an HTML tooltip to to all the DOM nodes set with this cssClass (for more elaborate content such as presenting a bigger version of a card).

IMPORTANT: all concerned nodes must exist and have IDs to get tooltips.

=== Removing static tooltips ===

'''this.removeTooltip(nodeId: string): void'''

Remove a tooltip from the DOM node with given id.

=== Advanced tooltips ===

'''force tooltip to open'''

If you want to force tooltip to open in reaction to some other action, i.e. click you can do this

this.tooltips[id].open(id)

where id is the id of the tooltip node where tooltip was installed.

'''dynamic tooltips'''

See [[BGA_Studio_Cookbook#Dynamic_tooltips]]

'''tooltips on mobile'''

Tooltips is very unreliable on mobile, it is recommended to implement some other method to obtaining same information,
such as simple click handler in dedicated "Help" mode or provide dedicated clickable areas such as corner of card.

== Warning messages ==

Sometimes, there is something important that is happening in the game and you have to make sure all players get the message. Most of the time, the evolution of the game situation or the game log is enough, but sometimes you need something more visible.

Ex: someone fulfills one of the end of the game conditions, so this is the last turn.

'''this.showMessage(msg: string, type: string): void'''

showMessage shows a message in a big rectangular area on the top of the screen of the current player, and it dissapears after few seconds (also it will be in the log in some cases).

* "msg" is the string to display. It should be translated.
* "type" can be set to "info", "error", "only_to_log" or custom string. If set to "info", the message will be an informative message on a white background. If set to "error", the message will be an error message on a red background and it will be added to log. If set to "only_to_log", the message will be added to the game log but will not popup at the top of the screen.
If set to custom string, it will be transparent, to use custom type define "head_xxx" in css, where xxx is the type. For example if you want yellow warning, use "warning" as type and add this to css:
.head_warning {
background-color: #e6c66e;
}

Important: the normal way to inform players about the progression of the game is the game log. The "showMessage" is intrusive and should not be used often.

<pre>
notif_messageinfo: function(notif) {
if (!g_archive_mode) {
var message = this.format_string_recursive(notif.log, notif.args);
this.showMessage(_('Announcement:') + " " + message, 'info');
}
},
</pre>

Show message could be used on the client side to prevent user wrong moves before it is send to server.
Example from 'battleship':
<pre>
onGrid: function(event) {
if (checkIfPlayerTriesToFireOnThemselves(event)) {
this.showMessage(_('This is your own board silly!'), 'error');
return;
}
...
},
</pre>

'''this.showMoveUnauthorized(): void'''

Shows predefined user error that move is unauthorized now

<pre>
onPet: function(event) {
if (checkPet(event)==false) {
this.showMoveUnauthorized();
return;
}
...
},
</pre>

== Dialogs ==

=== Confirmation dialog ===

When an important action with a lot of consequences is triggered by the player, you may want to propose a confirmation dialog.

CAREFUL: the general guideline of BGA is to AVOID the use of confirmation dialogs. Confirmation dialogs slow down the game and bother players. The players know that they have to pay attention to each move when they are playing online.

The situations where you should use a confirmation dialog are the following:
* It must not happen very often during a game.
* It must be linked to an action that can really "kill a game" if the player does not pay attention.
* It must be something that can be done by mistake (ex: a link on the action status bar).

'''this.confirmationDialog(message: string, yesHandler: (param: any) => void, noHandler?: (param: any) => void, param?: any): void'''

* message - message will be shown to user, use _() to translate
* yesHandler - non-optional handler to be called on yes
* noHandler - optional handler to called on no
* param - if specified, it will be passed to both handlers
NOTE: this is async function, it does not return anything and you should not do anything after, you must do everything in handlers

How to display a confirmation dialog:
<pre>
this.confirmationDialog(_("Are you sure you want to bake a pie?"), () => {
this.bakeThePie();
});
return; // nothing should be called or done after calling this, all action must be done in the handler
</pre>
With param and both handlers
<pre>
this.confirmationDialog(_("Are you sure you want to bake a pie?"),
(ingredient) => this.bakeThePie(ingredient),
(ingredient) => console.log(`cancelled baking of ${ingredient}`),
'apple');
</pre>

=== Multiple choice dialog ===

You can use this dialog to give user a choice with small amount of options

'''this.multipleChoiceDialog(message: string, choices: string[], callback: (choice: number) => void): void'''
* message - message will be shown to user, use _() to translate
* choices - array of choices
* callback - non-optional handler to be called on choice made, the choice parameter is the INDEX of the choice from the array of choices

NOTE: this is async function, it does not return anything and you should not do anything after, you must do everything in handlers
NOTE: there is no cancel handler, so make sure you gave user a choice to get out of it

Example:
<pre>
const keys = ["0", "1", "5", "10"];
this.multipleChoiceDialog(_("How many bugs to fix?"), keys, (choice) => {
if (choice==0) return; // cancel operation, do not call server action
var bugchoice = keys[choice]; // choice will be 0,1,2,3 here
this.bgaPerformAction("fixBugs", { number: bugchoice });
});
return; // must return here
</pre>

=== Generic Dialogs ===

As a general rule, you shouldn't use dialogs windows.

BGA guidelines specify that all game elements should be displayed on the main screen. Players can eventually scroll down to see game elements they don't need to see anytime, and you may eventually create anchors to move between game area section. Of course dialogs windows are very practical, but the thing is: all players know how to scroll down, and not all players know how to show up your dialog window. In addition, when the dialog shows up, players can't access the other game components.

Sometimes although, you need to display a dialog window. Here is how you do this:

// Create the new dialog over the play zone. You should store the handler in a member variable to access it later
this.myDlg = new ebg.popindialog();
this.myDlg.create( 'myDialogUniqueId' );
this.myDlg.setTitle( _("my dialog title to translate") );
this.myDlg.setMaxWidth( 500 ); // Optional

// Create the HTML of my dialog.
// The best practice here is to use [[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl#Javascript_templates|Javascript templates]]
var html = this.format_block( 'jstpl_myDialogTemplate', {
arg1: myArg1,
arg2: myArg2,
...
} );

// Show the dialog
this.myDlg.setContent( html ); // Must be set before calling show() so that the size of the content is defined before positioning the dialog
this.myDlg.show();

// Now that the dialog has been displayed, you can connect your method to some dialog elements
// Example, if you have an "OK" button in the HTML of your dialog:
dojo.connect($('my_ok_button'), 'onclick', this, (event) => {
event.preventDefault();
this.myDlg.destroy();
});

If necessary, you can remove the default top right corner 'close' icon, or replace the function called when it is clicked:
// Removes the default close icon
this.myDlg.hideCloseIcon();

// Replace the function call when it's clicked
this.myDlg.replaceCloseCallback((event) => { ... });

=== Scoring dialogs ===

Sometimes at the end of a round you want to display a big table that details the points wins in each section of the game.

Example: in Hearts game, we display at the end of each round the number of "heart" cards collected by each player, the player who collected the Queen of Spades, and the total number of points loose by each player.

Scoring dialogs are managed entirely on '''PHP side''', but they are described here as their effects are visible only on client side.

Displaying a scoring dialog is quite simple and is using a special notification type: "tableWindow":
<pre>
// on PHP side:
$this->notifyAllPlayers( "tableWindow", '', array(
"id" => 'finalScoring',
"title" => clienttranslate("Title of the scoring dialog"),
"table" => $table
));
</pre>

The "table" argument is a 2 dimensional PHP array that describes the table you want to display, line by line and column by column.

Example: display an 3x3 array of strings
<pre>
$table = [
[ "one", "two", "three" ], // This is my first line
[ "four", "five", "six" ], // This is my second line
[ "seven", "height", "nine" ] // This is my third line
];
</pre>

As you can see above, in each "cell" of your array you can display a simple string value. But you can also display a complex value with a template and associated arguments like this:
<pre>
$table = [
[ "one", "two", [ "str" => clienttranslate("a string with an ${argument}"), "args" => [ 'argument' => 'argument_value' ] ] ],
[ "four", "five", "six" ],
[ "seven", "height", "nine" ]
];
</pre>

This is especially useful when you want to display player names with colors. Example from "Hearts":
<pre>
$firstRow = [ '' ];
foreach( $players as $player_id => $player ) {
$cell = [ 'str' => '${player_name}',
'args' => [ 'player_name' => $player['player_name'] ],
'type' => 'header'
];
$firstRow[] = $cell;
}
$table[] = $firstRow;
...
</pre>

You can also use three extra attributes in the parameter array for the notification:
* '''header''': the content for this parameter displays before the table (also, the html will be parsed and player names will be colored according to the current game colors).
* '''footer''': the content for this parameter displays after the table (no parsing for coloring the player names)
* '''closing''': if this parameter is used, a button will be displayed with this label at the bottom of the popup and will allow players to close it (more easily than by clicking the top right 'cross' icon).

<pre>
$this->notifyAllPlayers( "tableWindow", '', [
"id" => 'finalScoring',
"title" => clienttranslate("Title of the scoring dialog"),
"table" => $table,
"header" => ['str' => clienttranslate('Table header with parameter ${number}'),
'args' => [ 'number' => 3 ],
],
"footer" => '<div class="myfoot"></div>',
"closing" => clienttranslate( "Closing button label" )
] );
</pre>

Note: currently id is not used - so you cannot access resulting div by id on js side
Note: any traslatable stirng have to be wrapped by clienttranslate() on top level OR it has to be recursive template.

DO NOT DO THIS:
<pre>
"footer" => '<div>'.clienttranslate( "The end" ).'</div>', // this will not work for translations!!!
</pre>

=== Scoring animated display ===

Sometimes, you may want to display a score value over an element to make the scoring easier to follow for the players (Terra Mystica final scoring for example).
You can do it with:

'''this.displayScoring(anchor_id: string, color: string, score: number | string, duration?: number, offset_x?: number, offset_y?: number): void'''

'''anchor_id''': ID of the html element to place the animated score onto (without the '#')

'''color''': hexadecimal RGB representation of the color (should be the color of the scoring player), but without a leading '#'. For instance, 'ff0000' for red.

'''score''': numeric score to display, prefixed by a '+' or '-'

'''duration''': animation duration in milliseconds (optional, default is 1000)

'''offset_x''' and '''offset_y''': if both offset_x and offset_y are defined and not null, apply the following offset (in pixels) to the scoring animation.
Note that the score is centered in the anchor, so the offsets might have to be negative if you calculate the position.

Note: if you want to display successively each score, you can use ''this.notifqueue.setSynchronous()'' function.
<pre>
setupNotifications: function() {
dojo.subscribe( 'displayScoring', this, "notif_displayScoring" );
...
}
...

notif_displayScoring: function(notif) {
const duration = notif.args.duration?notif.args.duration:1000;
this.notifqueue.setSynchronous('displayScoring', duration );
this.displayScoring( notif.args.target, notif.args.color, notif.args.score, duration);
},
</pre>

=== Speech bubble ===

For better interactivity in some games (Love Letter for example), you may use comic book style speech bubbles to express the players voices.
This is done with showBubble:

'''this.showBubble(anchor_id: string, text: string, delay?: number, duration?: number, custom_class?: string): void'''

* anchor_id - where to attach the bubble
* text - what to put in bubble, can be html
* delay - delay in milliseconds (optional, default 0)
* duration - duration of animation in milliseconds (optional, default 3000)
* custom_class - extra class to add to bubble (optional), if you need to override the default bubble style

<pre>
this.showBubble('meeple_2', _('Hello'), 0, 1000, 'pink_bubble');
</pre>

<pre>
notif_speechBubble(notif) {
var html = this.format_string_recursive(notif.args.text, notif.args.args);
this.showBubble(notif.args.target, html, notif.args.delay ?? 0, notif.args.duration ?? 1000);
},
</pre>

'''Warning''': if your bubble could overlap other active elements of the interface (buttons in particular), as it stays in place even after disappearing, you should use a custom class to give it the style "pointer-events: none;" in order to intercept click events.

Note: If you want this visually, but want to take complete control over this bubble and its animation (for example to make it permanent) you can just use div with 'discussion_bubble' class on it, and content of div is what will be shown.

== Translations ==

See [[Translations]]

== Players panels ==

=== Update players score ===

The column player_score from the player table is automatically loaded into this.scoreCtrl and therefore into the stars location on the player board. This occurs sometime after the game setup() function. However this score must be updated as the game progresses using notifications.

Note: this.scoreCtrl[player_id] is object of class [[Counter]], you can use other counter API.

Increase a player score (with a positive or negative number):

<pre>
this.scoreCtrl[ player_id ].incValue( score_delta );
</pre>

Set a player score to a specific value:

<pre>
this.scoreCtrl[ player_id ].setValue( new_score );
</pre>

Set a player score to a specific value with animation:

<pre>
this.scoreCtrl[ player_id ].toValue( new_score );
</pre>

Typical usage would be (that will process 'score' notification):
<pre>
setupNotifications : function() {
...
dojo.subscribe('score', this, "notif_score");
},
notif_score: function(notif) {
this.scoreCtrl[notif.args.player_id].setValue(notif.args.player_score);
},
</pre>

=== Adding stuff to player's panel ===

At first, create a new "JS template" string in your template (tpl) file:

(from Gomoku example)
<pre>
var jstpl_player_board = '\<div class="cp_board">\
<div id="stoneicon_p${id}" class="gmk_stoneicon gmk_stoneicon_${color}"></div><span id="stonecount_p${id}">0</span>\
</div>';
</pre>

Then, you add this piece of code in your JS file to add this template to each player panel:

<pre>
// Setting up player boards
for( var player_id in gamedatas.players )
{
var player = gamedatas.players[player_id];

// Setting up players boards if needed
var player_board_div = $('player_board_'+player_id);
dojo.place( this.format_block('jstpl_player_board', player ), player_board_div );
}
</pre>

(Note: the code above is of course from your "setup" function in your Javascript).

Very often, you have to distinguish current player and others players. In this case, you just have to create another JS template (ex: jstpl_otherplayer_board) and use it when "player_id" is different than "this.player_id".

=== Fixing Player Panel heights ===

You may find that the player panels don't automatically resize when adding something to (or removing something from) a player panel while the display is in portrait mode (i.e. the player summary panels are at the top of the screen rather than down the right side).

When this happens, call <pre>this.adaptPlayersPanels();</pre> This recalculates the layout and also adjusts the position of the actionbar for you.

=== Player's panel disabling/enabling ===

'''this.disablePlayerPanel(player_id: number): void'''

Disable given player panel (the panel background become gray).

Usually, this is used to signal that this played passes, or will be inactive during a while.

Note that the only effect of this is visual. There are no consequences on the behaviour of the panel itself.

'''this.enablePlayerPanel(player_id:number): void'''

Enable a player panel that has been disabled before.

'''this.enableAllPlayerPanels(): void'''

Enable all player panels that has been disabled before.

=== Player order ===

'''this.updatePlayerOrdering(): void'''

This function makes sure that player order in player's panel matches this.gamedatas.playerorder and its normally called by framework.
You can call it yoursel if you change this.gamedatas.playerorder from notification.
Also you can override this function to change defaults OR insert a non-player panel [[BGA_Studio_Cookbook#Inserting_non-player_panel]].

=== Counters ===
Note: there is bga component called "ebg/counter" this API is not using it, these methods
below declared right in core game. If you need animation for counters use ebg/counter

To use this API just create a counter dom element like this (class does not really matter)
<pre>
<div class="counter" id="bread"></div>
<div class="counter" id="coin"></div>
</pre>
The "bread" will the counter name.

The php code should send all "counters" data from getAllDatas() method like this

game.php
<pre>
protected function getAllDatas() {
// (the key must match counter_name)
$result['counters']=[
'bread' => [
'counter_name' => 'bread',
'counter_value' => 3
],
'coin' => [
'counter_name' => 'coin',
'counter_value' => 5
]
];
return $result;
}
</pre>

'''setCounter(counter_name: stirng, new_value: string | number): void'''

updates the global this.gamedatas.counters and value of node $(counter_name)
<pre>
notif_counter: function(notif) {
this.setCounter(notif.args.counter_name, notif.args.counter_value);
},
</pre>

'''incCounter(counter_name: string, delta: number): void'''
<pre>
notif_counter : function(notif) {
this.incCounter(notif.args.counter_name, notif.args.inc);
},
</pre>

'''updateCounters(counters: object): void'''

Useful for updating game counters in the player panel (such as resources).
'counters' arg is map of counters (the key must match counter_name)
{
'bread': {
'counter_name' : 'bread',
'counter_value' => 3
},
'coin': {
'counter_name' : 'coin',
'counter_value' => 5
}
}
All counters MUST be referenced in this.gamedatas.counters (means they should be send from php) and will be updated.
DOM objects referenced by 'counter_name' will have their innerHTML updated with 'counter_value'.

Usually you call this from notification

<pre>
notif_counter : function(notif) {
this.updateCounters(notif.args.counters);
},
</pre>

== BGA GUI components ==

BGA framework provides some useful ready-to-use components for the game interface:

[[Studio#BGA_Studio_game_components_reference]]

Note that each time you are using an additional component, you must declare it at the top of your Javascript file in the list of modules used.

Example if you are using "ebg.stock":
<pre>
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/stock" /// <=== we are using ebg.stock module
],
</pre>

== BGA Buttons ==

=== Basic Button ===

'''this.addActionButton(id: string, label: string, method: string | eventhandler, destination?: string, blinking?: boolean, color?: string): void'''

You can use this method to add an action button in the main action status bar (or other places).

Arguments:
* id: an element ID that should be unique in your HTML DOM document.
* label: the text of the button. Should be translatable (use _() function). Note: this can also be any html, such as "<div class='brick'></div>", see example below on how to make image action buttons.
* method: the name of your method that must be triggered when the player clicks on this button (can be name of the method on game class or handler).
* destination (optional): id of parent on where to add button, ONLY use in rare cases if location is not action bar. Use '''null''' as value if you need to specify other arguments.
* blinking (optional): if set to '''true''', the button is going blink to catch player's attention. Please DO NOT abuse blinking button. If you need button to blink after some time passed add class 'blinking' to the button later.
* color: could be '''blue''' (default), '''red''','''gray''' or '''none'''.

You should only use this method in your "onUpdateActionButtons" method. Usually, you use it like this:

<pre>
onUpdateActionButtons: function( stateName, args ) {
if (this.isCurrentPlayerActive()) {
switch( stateName ) {
case 'giveCards':
this.addActionButton( 'giveCards_button', _('Give selected cards'), 'onGiveCards' );
this.addActionButton( 'pass_button', _('Pass'), () => this.bgaPerformAction('actPass') );
break;
}
}
},
</pre>

In the example above, we are adding a "Give selected cards" button in the case we are on game state "giveCards". When player clicks on this button, it triggers our "onGiveCards" method.

Example using blinking red button:
<pre>
this.addActionButton( 'button_confirm', _('Confirm?'), 'onConfirm', null, true, 'red');
</pre>

If you want to call the handler with arguments, you can use arrow functions, like this:
<pre>
this.addActionButton( 'commit_button', _('Confirm'), () => this.onConfirm(this.selectedCardId), null, false, 'red');
</pre>

=== Image Button ===

You can use the same method, but add extra class to a button to disable the padding and style it, i.e.
<pre>
this.addActionButton( 'button_brick', '<div class="brick"></div>', ()=>{... on brick ...}, null, null, 'gray');
dojo.addClass('button_brick','bgaimagebutton');
</pre>

where

<pre>
.bgaimagebutton {
padding: 0px 12px;
min-height: 28px;
border: none;
}
</pre>

If you use this a lot, you can define a helper function, i.e.
<pre>
/**
* This method can be used instead of addActionButton, to add a button which is an image (i.e. resource). Can be useful when player
* need to make a choice of resources or tokens.
*/
addImageActionButton: function(id, div, handler, bcolor, tooltip) {
if (typeof bcolor == "undefined") {
bcolor = "gray";
}
// this will actually make a transparent button id color = gray
this.addActionButton(id, div, handler, null, false, bcolor);
// remove border, for images it better without
dojo.style(id, "border", "none");
// but add shadow style (box-shadow, see css)
dojo.addClass(id, "shadow bgaimagebutton");
// you can also add additional styles, such as background
if (tooltip) {
dojo.attr(id, "title", tooltip);
}
return $(id);
},
</pre>

=== Disabling Button ===

You can disable the '''bgabutton''' by adding the css class '''disabled''' in you js. The disabled button is still visible but is grey and not clickable.
For example in the '''onUpdateActionButtons''' :
<pre>
this.addActionButton('play_button_id', _('Play 1 to 3 cards'), 'playFunctionButton');
if (condition) {
dojo.addClass('play_button_id', 'disabled');
}
</pre>

=== Custom Buttons ===

You can create a custom button, but the BGA framework provides a standard button that requires only .css classes: '''bgabutton''' and '''bgabutton_${color}'''.

'''Examples:'''

<pre>
<a href="#" id="my_button_id" class="bgabutton bgabutton_blue"><span>My blue button</span></a>

<a href="#" id="my_button_id" class="bgabutton bgabutton_red bgabutton_big"><span>My big red button</span></a>
</pre>

'''Note''': To see it in action, check out ''Coloretto''.

=== Button outside of action bar ===

Use addActionButton() method with destination argument set
<pre>
this.addActionButton( 'commit_button', _('Confirm'), 'onConfirm', 'player_board', true, 'red');
</pre>

in example above the button will be place on object with id 'player_board'

== Image loading ==

See also [[Game_art:_img_directory]].

'''Be careful''': by default, ALL images of your img directory are loaded on a player's browser when he loads the game. For this reason, don't let in your img directory images that are not useful, otherwise it's going to slowdown the game load.

'''this.dontPreloadImage(image_file_name: string)'''

Using dontPreloadImage, you tell the interface to not preload a specific image in your img directory.

Example of use:
<pre>
this.dontPreloadImage( 'cards.png' );
</pre>

This is particularly useful if for example you have 2 different themes for a game. To accelerate the loading of the game, you can specify to not preload images corresponding to the other theme.

Another example of use: in "Gosu" game with Kamakor extension, you play with 5 sets of cards among 10 available. Cards images are organized by sets, and we only preload the images corresponding to the 5 current sets with '''ensureSpecificGameImageLoading( image_file_names_array )'''.
<pre>
// By default, do not preload anything
this.dontPreloadImage( 'cards.png' );
this.dontPreloadImage( 'clan1.png' );
this.dontPreloadImage( 'clan2.png' );
this.dontPreloadImage( 'clan3.png' );
this.dontPreloadImage( 'clan4.png' );
this.dontPreloadImage( 'clan5.png' );
this.dontPreloadImage( 'clan6.png' );
this.dontPreloadImage( 'clan7.png' );
this.dontPreloadImage( 'clan8.png' );
this.dontPreloadImage( 'clan9.png' );
this.dontPreloadImage( 'clan10.png' );
var to_preload = [];
for( i in this.gamedatas.clans )
{
var clan_id = this.gamedatas.clans[i];
to_preload.push( 'clan'+clan_id+'.png' );
}

this.ensureSpecificGameImageLoading( to_preload );

</pre>

'''Note:''' You don't need to specify to not preload game box images (game_box.png, game_box75.png...) since they are not preloaded by default.

'''this.ensureSpecificGameImageLoading(list: string[])'''

This is oppostive of dontPreloadImage - its ensure specific images is loaded. Note: only makes sense if preload list is empty, otherwise everything is loaded anyway

'''load specific images'''
All images that will be preloaded stored in g_img_preload. If you want to override it directly - there is no API, but you can do this in GAME constructor

g_img_preload = ['tokens.png', 'trains.png', 'loc_plan.png', 'eng.png', 'eng-back.png'];

You can also set it to empty array and call ensureSpecificGameImageLoading() on specific images

== Sounds ==

Add a custom sound and make it load with your interface:

Add this in your template (.tpl) file:
<pre>
<audio id="audiosrc_<gamename>_<yoursoundname>" src="{GAMETHEMEURL}img/<gamename>_<yoursoundname>.mp3" preload="none" autobuffer></audio>
<audio id="audiosrc_o_<gamename>_<yoursoundname>" src="{GAMETHEMEURL}img/<gamename>_<yoursoundname>.ogg" preload="none" autobuffer></audio>
</pre>

Note: this is a requirement to provide both a mp3 and a ogg file with the names <code><gamename>_<yoursoundname>[.ogg][.mp3]</code>.

Play the sound (from your .js file):

<pre>
playSound('<gamename>_<yoursoundname>'); // do not add 'this.' - its a global function
</pre>

Disable the standard "move" sound for this move (to replace it with your custom sound):

Add this to your notification handler:

<pre>
this.disableNextMoveSound();
</pre>

Note: it only disable the sound for the next move.

== Title bar and states ==

=== Client states ===

Client states is a way to simulate the state transition but without actually going
to server. It is usefull when you need to ask user multiple questions before you
send things to server

'''this.setClientState(newState: string, args: object)'''

Example:
this.setClientState("client_playerPicksLocation", {
descriptionmyturn : _("${you} must select location"),
});

For more information see [[BGA_Studio_Cookbook#Multi_Step_Interactions:_Select_Worker.2FPlace_Worker_-_Using_Client_States]]

'''this.restoreServerGameState()'''
If you are in client state it will restore the current server state (cheap undo)

'''this.on_client_state'''
Boolean indicating that we are in client state

=== Title bar ===
If you simply want to show something in title bar you can do it directly
$('pagemaintitletext').innerHTML = text;

This however will not work with parameters and will not draw You in color,
if you want to do proper args rendering use method below

;'''this.removeActionButtons()'''
Removes all buttons from title bar

;'''this.updatePageTitle()'''
:This function allows to update the current page title and turn description according to the game state arguments. If the current game state description this.gamedatas.gamestate.descriptionmyturn is modified before calling this function it allows to update the turn description without changing state. This will handle arguments substitutions properly.

Note: this functional also will calls this.onUpdateActionButtons, if you want different buttons then state defaults, use method in example to replace them, if it becomes too clumsy use client states (see above)

Example from Terra Mystica:
<pre>
onClickFavorTile: function( evt ) {
...
if ( ... ) {
this.gamedatas.gamestate.descriptionmyturn = _('Special action: ') + _('Advance 1 space on a Cult track');
this.updatePageTitle();
this.removeActionButtons();
this.addActionButton( ... );
...
return;
}
...

}
</pre>

== User preferences ==
'''this.getGameUserPreference(pref_id)'''

Return the value of a user preference. It will return the value currently selected in the select combo box, in the top-right menu.

'''this.setGameUserPreference(pref_id, value)'''

Programmatically change a user preference. It will have the same effect as if the player changed the value in the select combo box, in the top-right menu.

'''this.onGameUserPreferenceChanged'''

A callback you can define if you want to be notified when a user changes a user preference.

Example:<pre>
onGameUserPreferenceChanged: function(pref_id, pref_value) {
switch (pref_id) {
case 201:
document.getElementsByTagName('html')[0].classList.toggle('dark-background', pref_value == 2);
break;
}
}
</pre>

== Other useful stuff ==

'''dojo.hitch'''

With dojo.hitch, you can create a callback function that will run with your game object context whatever happen.

Typical example: display a BGA confirmation dialog with a callback function created with dojo.hitch:

<pre>
this.confirmationDialog( _('Are you sure you want to make this?'), dojo.hitch( this, function() {
this.bgaPerformAction('makeThis');
} ) );
</pre>

In the example above, using dojo.hitch, we ensure that the "this" object will be set when the callback is called.

NOTE: In modern JS there are lambdas that eliminate need for that, the example above will look like this
<pre>
this.confirmationDialog( _('Are you sure you want to make this?'), () => this.bgaPerformAction( 'makeThis') );
</pre>

;'''onScreenWidthChange()'''
:This function can be overridden in your game to manage some resizing on the client side when the browser window is resized. This function is also triggered at load time, so it can be used to adapt to the :viewport size at the start of the game too.

; this.bRealtime
: Return true if the game is in realtime. Note that having a distinct behavior in realtime and turn-based should be exceptional.

; g_replayFrom
: Global contains replay number in live game, it is set to undefined (i.e. not set) when it is not a replay mode, so consequentially the good check is '''typeof g_replayFrom != 'undefined'''' which returns true if the game is in replay mode <i>during the game</i> (the game is ongoing but the user clicked "replay from this move" in the log)

; g_archive_mode
: Returns true if the game is in archive mode <i>after the game</i> (the game has ended)

; this.instantaneousMode
: Returns true during replay/archive mode if animations should be skipped. Only needed if you are doing custom animations. (The BGA-provided animation functions like <i>this.slideToObject()</i> automatically handle instantaneous mode.)
: Technically, when you click "replay from move #20", the system replays the game from the very beginning with moves 0 - 19 happening in instantaneous mode and moves 20+ happening in normal mode.

; g_tutorialwritten
: Returns an object like the below if the game is in tutorial mode, or undefined otherwise. Tutorial mode is a special case of archive mode where comments have been added to a previous game to teach new players the rules.
{
author: "91577332",
id: "576",
mode: "view"
status: "alpha"
version_override: null
viewer_id: "84554161"
}

'''getBgaEnvironment(): string'''
: Returns "studio" for studio and "prod" for production environment (i.e. where games current runs). Only useful for debbugging hooks.
Note: alpha server is also "prod"

[[Category:Studio]]

Translations

2024-09-23T09:37:25Z

Sguzzer Gunayer: /* How to not make translators crazy ;) */

{{Studio_Framework_Navigation}}

Using BGA Studio, the game you create is ready to be translated to each language by the BGA community. To make this possible, you only need to specify which string must be translated and how to combine them.

__TOC__

== Localization Overview ==

Localization for BGA games happens largely on the CLIENT. Games must be developed in English and English strings are sent to the client.

It's only at the client that your English strings will be displayed with the translation for the user's language, when such a translation exists.

For anyone who has worked on a system where translation happens at the server and localized strings are sent to the client: you must unlearn what you have learned. Just stick with English and send the untranslated English strings. The magic happens at the client.

== How will my strings be translated? ==

When developing your game, all strings must be in English. Strings must be coherent with the English version of the game.

Once your game enters Beta, the BGA player community will descend upon your game like a plague of locusts and translate it into dozens of languages before you can say "Je ne parle pas anglais".

== What do I have to do from a programming standpoint? ==

Not as much as you think. Read on for full details, but the golden rules are:

# Make sure that any string on the server side that needs to be translated on the client side is wrapped in a clienttranslate() function when defined. For example: $my_response = clienttranslate('Hey translators, please translate this string'). clienttranslate doesn't actually do anything at all (it just passes the text through) but the translation engine searches your code for strings wrapped in that function and uses them to build the list of strings that need to be translated.
# On the client side, just display your text, but wrap it in _().
## If you pass a string constant to _() - such as _('This is my string') then the parser will automatically detect and add your string to the list of strings that need to be translated, AND it will display the local translation for it when displaying.
## If you pass a variable to _() - such as _(args.my_message) then MAKE SURE that the variable is set to an English string that is either defined somewhere in your PHP code in a clienttranslate() function or somewhere else in your javascript code in a _() function. As long as it is, the translators will provide translations for it, and the _() function will display the local translation of your English string.
# A string used as the message for notifyAllPlayers or notifyPlayer will automatically have its translation displayed on the client - you don't need to do anything EXCEPT make sure that it is wrapped in a clienttranslate() on the server, so that it gets translated.
# A string used as the "description" or "descriptionmyturn" for a state in your state machine will also be automatically translated on the client - you don't need to do anything EXCEPT make sure that it is wrapped in a clienttranslate() on the server, so that it gets translated.
# A string used in the pre-games option screen will also automatically have any translation displayed at the client - you don't need to do anything EXCEPT make sure that it is wrapped in a totranslate() on the server (nota bene: you should not use clienttranslate() here as this file is processed specifically and those strings will not be included in the game translation file but in the main site translation file - with a prefix to keep translations isolated by module - as they have to be translated on main site pages. If you need exactly the same string in your game for a client side translation, it should be declared somewhere else in your code wrapped inside a clienttranslate() to be included in the game translation file.
# A string used in the statistics screen will operate like a string in the pre-game options screen. It will automatically have any translation displayed at the client as long as you make sure that it is wrapped in a totranslate() on the server.
# If you are using parameters for a call to notifyAllPlayers or notifyPlayers, or for a state's "description" or "descriptionmyturn" and those parameters contain text that needs to be translated, you will need to tell the system to display the translated versions of them by using the 'i18n' argument. See below for full details.

== What strings should be marked for translation ==

YES:
* Every text that can be visible by the player when the game is running normally. This includes tooltips, texts on cards, error messages.

NO:
* Error messages that are not supposed to happen (unexpected errors).
* Player names (i.e. do not put player_name or any php key send via notification which is essentially a player name, such as 'other_player' in 'i18n' array)
* Proper names of characters or places in some cases (consult the publisher)
* Numbers (i.e _("42"))
* Keywords used internally

== What rules should I follow for the original English strings? ==

For a coherent and homogeneous interface, here are some rules about ending a sentence with a final period '.'

* As a general rule:
** If a sentence is displayed isolated in the interface => no final period
** If a sentence is followed or could be followed by another sentence in the same interface space => final period.

* In detail:
** No final period:
*** button labels
*** section titles
*** menu elements
*** links triggering an isolated action
*** anything that is not a full sentence
*** current actions in the status bar
** Final period:
*** complete sentences (e.g., explanations and descriptions) that can be chained with other sentences
** Either a period or no period is acceptable (but this should be consistent throughout the game) for:
*** isolated tooltips / small sentences
*** game logs (no period is usually preferable)
*** error messages (unless there is more than one sentence in the error message; final period is mandatory in this case)

Otherwise, you should try to follow as closely as possible the general style and format (including capitalization) used in the published English rulebook and game materials.

== Focus on translating notifications ==

Usually, translating a website is simple: you just call a function on every string you have to translate, and the string is translated in the player's language. On Board Game Arena, this is exactly the same with the "_( string )" function.

However, there is one difference on BGA: notifications. The server is sending notifications to players, and most of the time the notifications are the same for every players, no matter what language each player is using. This is why notifications are translated on client side in the proper language, even if the strings are defined on server side.

== How to not make translators crazy ;) ==

* Try to reuse the exact same strings (with the same case, etc.) to minimize the number of strings to translate.
** '''Example''': Consider replacing <pre>self::_("Winner")</pre> and <pre>self::_("Winners")</pre> (two strings to translate) with <pre>self::_("Winner(s)")</pre>
** '''Example 2''': <pre>clienttranslate("play a card")</pre> and <pre>clienttranslate("Play a card")</pre> means there will be two strings to translate.
* Do not mark as translatable a game element that does not have to be translated (ex: if the name of a monster on a card is "Zzzzz", maybe there's no need to translate it).
* Words does not come in the same order in each language. Thus, when you have to translate a string with an argument, do not write something like:
<pre>self::_("First part of the string, ").$argument.' '.self::_("second part of the string")</pre>
Write instead:
<pre>sprintf( self::_("First part of the string, %s second part of the string"), $argument )</pre>
(or the equivalent "dojo.string.substitute" in Javascript)
* This also applies to punctuation marks. I.e. this is not good: _("Pick")+":"
* When translators are going to translate your game, the most difficult task for them is to get the context of the string to be translated. The shorter the string is, the more difficult the task is for them. As a rule of thumb, try to avoid short, insignificant strings that require knowledge of their surrounding context. You can also leave a comment on the context of the string in the translation program (English to English) if you are the developer of the game.
* Use same sentence for plural vs singular. We prefer to write "player gets 1 coin(s)" (or "coin/s") rather than write two versions of the same string for plural and singular - it reduces the number of strings to translate. Also using the icon to represent coin in logs may solve this issue.
* Instead of writing elaborate strings like "With the effect of ZZZ, player XXX gains a new YYY", which is very difficult to translate, write strings like "ZZZ: XXX gets YYY".
* Use present tense instead of past. E.g., "player gets wood" instead of "player got wood".
* Avoid using gender-specific wording as much as possible.
* Also avoid "their". There is [[https://forum.boardgamearena.com/viewtopic.php?f=11&t=19432&start=10#p88592 a pronoun replacement system]] is in place, and cannot work if your use "their" as a singular genderless pronoun, as it removes the information that it's singular. E.g., you should write "playerX returns card to *his* hand" or "playerX returns card to *his/her* hand" and not "playerX returns card to *their* hand" as in the 2 first case the system will substitute the proper pronoun his/her/their depending on playerX declared/undeclared gender, but in the second case it will always stay "their" whatever the player preference setting. In some case its actually needed, for example if you say "King sends his troops" in the log and King is not a player name, but character in the game - it will be changed to "her" if a player is female, which is not correct, in this case their would be appropriate (or just "the troops")
* Where two strings are identical apart from (say) a number, use the same string with a ${parameter}, and call format_string_recursive (on the client) or use args (for notifications and state descriptions) to provide the details. But *never* do that for composing multiple sentences with words: other languages have different grammar and it would most likely create untranslatable strings.

== WARNING: Make sure your strings will be translated! ==

For each game, our translation tool does a full scan of the code, looking for translation markers like "_()" or "clienttranslate()". (See below for the full list of translation markers.)

If your original string is not completely contained inside one of these markers, it won't be translated.

<pre>
// Examples: the following strings will be translated:
var mystring_translated = _("my string"); // JS
$mystring_translated = self::_("my string"); // PHP
$mystring_translated = sprintf( self::_("my string with an %s argument"), $argument ); // PHP

// Examples: the following strings WILL NOT be translated:
$my_string = "my string";
$not_translated = self::_( $my_string ); // The original string is not contained within a translator marker => no translation
$not_translated = self::_( sprintf( "my string with a %s argument", $argument ) ); // Ditto
</pre>

== On client side (Javascript) ==

On client side, things are quite simple: you just have to use the "_()" function for all strings you want to translate.

Examples:
<pre>
// Get a string in player's language:
var translated = _("original english string");

// Get a string in player's language with parameter:
var translated = dojo.string.substitute( _("You can pick ${p} cards and discard ${d}"), {
p: 2,
d: 4
} );
</pre>

'''WARNING:''' in Javascript strings to translate, you should never use '\n', '\t' or such, as it will break the translation bundle and result in all the Javascript translation to fail. In any case, the strings will result in HTML code, and such character codes won't have any impact on the HTML rendering. You should use HTML markup instead.

'''ANOTHER WARNING:''' you cannot use this function _() in the javascript object constructor, but you can achieve the same if you use it the setup method. If you do that you will see this error in browser debug console:
Try to use a translated string in JS object declaration : impossible => string is NOT translated

=== Formatting on client side ===

Sometimes you will want to apply some formatting on the client side, but don't want to put HTML tags within the source string (which may be confusing for translators).

This can be achieved with the <code>bga_format</code> function and Markdown-style syntax.

<pre>
/**
* @function bga_format
* Replaces delimiters with HTML tags in translated text
* @param {string} translated string
* @param {Object} map of replacements to make, should be of the form
* {
* '*': (t) => t,
* '_': 'classname',
* }
* keys are delimiters within the translated string
* values are either strings (classname of surrounding span) or function (flexible replacements)
* @returns {string} Returns the original string, with replacements made.
*/
</pre>

Example:
<pre>
// Get a string in player's language:
bga_format(_('You receive a *special* _tile_'), {
'*': (t) => '<b>' + t + '</b>',
'_': 'tile-name'
});
</pre>

The above will return something along the lines of:
<pre>
You receive a <b>special</b> <span class="tile-name">tile</span>
</pre>

Or, if the user is playing in Spanish, for example:
<pre>
Recibes una <span class="tile-name">loseta</span> <b>especial</b>
</pre>

Notes:
* The text passed to <code>bga_format</code> must still be translated using <code>_()</code>, don't forget it!
* Good characters to demarcate formatting are: <code>['*', '_']</code> (other single characters will work, just make sure it will be clear to a translator)
* If the replacements object is a string, the inner text will be placed within a <code><span></code> tag with the string as a class
* If the replacements object is a function, the inner text will be passed as an argument to the function, and the return value will replace the text and the delimiters

== On server side (PHP) ==

On PHP side, you can use 3 different functions to specify that a string must be translated.

=== Function clienttranslate ===

'''clienttranslate( 'string to translate' ):'''

This function is ''transparent'': it will return the original English string without any change. Its only purpose is to mark this string as "must be translated", and to make sure the translated version of the string will be available on client side.

In general, you use clienttranslate:
* In your '''states.inc.php''', for the fields "description" and "descriptionmyturn".

<pre>
"description" => clienttranslate('${card_name}: ${actplayer} must discard 4 identical energies'),
</pre>

* In '''material.inc.php''', when defining text for game materials that must be displayed on the client side.

<pre>
$this->card_types = array(

1 => array(
'name' => clienttranslate('Amulet of Air'), // Thus, we can use "_( card_name )" on Javascript side.
</pre>

* When sending a notification with ''notifyAllPlayers'' or ''notifyPlayer'', in the game log string and all game log arguments that need a translation.

<pre>
// A game log string with no argument:
self::notifyAllPlayers( 'pickLibraryCards', clienttranslate('Everyone draw cards from their library'), [] );
</pre>

As a consequence there is no point passing variables to this function. E.g.:

<pre>
notif="foo";
self::notifyAllPlayers( 'log', clienttranslate(notif),[]); // BAD

notif=clienttranslate("foo");
self::notifyAllPlayers( 'log', notif,[]); // GOOD

self::notifyAllPlayers( 'log', clienttranslate("player gains ${num} gems"),[num=>2]); // BAD it is dynamic string enterpreted by php
self::notifyAllPlayers( 'log', clienttranslate('player gains ${num} gems'),[num=>2]); // GOOD, difference is single quotes

self::notifyAllPlayers( 'log', clienttranslate("player gains ".${num}." gems"),[num=>2]); // BAD concatenation

</pre>

Translating arguments is a little bit more complex. This uses the '''i18n''' special argument as below:

<pre>
// In the following example, we translate the game log itself, but also the "card_name" argument:

self::notifyAllPlayers( 'winPoints', clienttranslate('${card_name}: ${player_name} gains ${points} point(s)'), array(
'i18n' => array( 'card_name' ), // <===== We specify here that "card_name" argument must be translated
'player_id' => $player_id,
'player_name' => self::getActivePlayerName(),
'points' => $points,
'card_name' => $this->card_types[8]['name'] // <==== Here, we provide original English string.
) );
</pre>

To ensure the translation of the i18n argument will be made, clienttranslate must have been used somewhere, for instance:

<pre>
$this->card_types = array(
...
8 => array(
'name' => clienttranslate("Amulet of Fire"),
...
</pre>

Pay attention when using the '''i18n''' argument when translating arguments for the client: do NOT use same argument for both translations AND key codes for client-side actions (like using 'card_name' to move it on the player board as described in the example). It's pretty obvious in the example, but it can be very tricky when translation is made at the end of the development (which is often the case). Use explicit argument names like 'card_name_translated' by example.

'''WARNING:''' you should NEVER use concatenation with ''clienttranslate'', as it would result in a different string to translate at runtime than the one retrieved statically in the translation system, and so translation would not be applied. If you need to compose a string, use substitution and the i18n parameter (but you also have to pay attention not to compose sentences in a way that is dependent upon the English language specific syntax, or it may be impossible to translate correctly in another language: sometimes, you need multiple full sentences rather than relying on substitution).

=== Method _ (underscore) ===

'''self::_( "my string to translate" ):'''

This function returns a string translated in the language of CURRENT user (i.e. player who send the request to the server) (be careful, this is NOT the active player).

This can be used like self::_('bla') or this->('bla'). You cannot use static underscore function _('bla') in php, it is not the same, it will not translate strings from your game.

The returned string will be surrounded by HTML tags, so you cannot use it in places where pure text is required or your string already has another html markup.

Most of the time, you don't need to translate strings on server side, except on the following situations:
* Throwing user exceptions
* Creating the labels for the game interface used in your template
* Rarely, in your material.inc.php, if for example you need to use some string elements in your exceptions
* Rarely, in your "getAllDatas" PHP method, as the data return by this method is used only by current user

Imporant! This function does two things:
* Mark string for translation
* Translates in runtime
As a consequence you absolutely cannot have $var in there! Or string concatenations.
I.e.
$food=self::_("Banana");// good
self::_("User gives $food to a cat"); // bad
For the translator we will have two strings "Banana" and "User gives $food to a cat", but in runtime we will be
"Banana" and "User gives Banana to a cat" and second string would not match anything. And this is as bad
self::_("User gives ".$food." to a cat");// bad

==== Throwing an exception because the player did a forbidden move ====

<pre>
// This will display a translatable red message to the player that just did some wrong action:
throw new BgaUserException( self::_('You must choose 3 cards') );
</pre>

Note that the use of BgaUserException signals that this exception is "expected". In theory, all exception that are expected should be translated.

<pre>
// this is the same but with variable
throw new BgaUserException(sprintf(self::_('You must choose %d cards'), $card_num));
</pre>

==== Creating labels ====

Simple label in tpl file (i.e. label which has same value independent of anything):

in .tpl:
<pre>
<div>{CARDS_FOR_YEAR_2}</div>
</pre>

in .view.php:
<pre>
$this->tpl['CARDS_FOR_YEAR_2'] = self::_("Your cards for year II");
</pre>

'''Nota bene:''' it is recommended to set translated text in your interface client side rather than use template variables and server translation, so that translation works natively in replays (that don't have server side translations). For simple strings, the framework will handle moving the translation client side, but for more complex strings it may not work. In particular, you should not use server side translation for templates with substitution variables (or use the specific function "gameview_str_replace( $search, $replace, $string )" if not possible otherwise or for old code compatibility). Also, you should never use a "to_translate" class in your .tpl as it is used internally by the framework.

Label which is generated based of player's name, using server side template:
in .tpl:
<pre>
<div id="empire_title_{COLOR}" class="side_title color_{COLOR}">{EMPIRE_LABEL}</div>
</pre>
in .view.php:
<pre>
$this->page->insert_block("player_board", array ("COLOR" => $color,"PLAYER_NAME" => $name,"PLAYER_NO" => $no,
"PLAYER_ID" => $player_id, "CLASSES" => $own?"own":"",
"EMPIRE_LABEL" => self::raw(gameview_str_replace('${player_name}', $name, self::_('${player_name}\'s EMPIRE')))
));
</pre>

Label which is generated based of player's name, using client side (which is better):
in .tpl:
<pre>
<div id="empire_title_{COLOR}" class="side_title color_{COLOR}">Stub</div>
</pre>
in .js:
<pre>
for (var player_id in this.gamedatas.players) {
var player_color = this.gamedatas.players[player_id].color;
var player_name = this.gamedatas.players[player_id].name;
$('empire_title_'+player_color).innerHTML=this.format_string_recursive(_("${player_name}'s EMPIRE"), {player_name: player_name});
}
</pre>

==== Translating strings in material file ====

Rarely, in your material.inc.php, if for example you need to use some string elements in your exceptions.

<pre>
// In material.inc.php, $this->energies[n]['nametr'] has been created with the self::_() method. Now we can do this:
throw new BgaUserException( self::_("To execute this action you need more: ").' '.$this->energies[$resource_id]['nametr'] );
</pre>

Note: you could also do this, so you don't need to pollute your material file
throw new BgaUserException( self::_("To execute this action you need more: ").' '.self::_($this->energies[$resource_id]['name']) );

where $this->energies[$resource_id]['name'] were marked in material file using regular clienttranslate function
<pre>
$this->energies = [
22 => [
'name' => clienttranslate('Sun')
...
]
];
</pre>

==== Strings in getAllDatas ====

Rarely, in your "getAllDatas" PHP method, as the data return by this method is used only by current user.

Note: not sure why would you send strings from the server in this case, as same can be achieved on the client usually.

=== Function totranslate ===

'''totranslate( "my string to translate" ):'''

This function works exactly like 'clienttranslate', except it tells BGA that the string is not needed on client side.

You should not use this function, except on the following cases:
* Statistics name in stats.inc.php
* Option names and option values name in gameoptions.inc.php

== Top Secret Undocumented Features ==

If your string contains the clause '$${value}' (such as 'You gain $${value}.') then the translation system seems to move the position of the $ to a localized location (eg $5 in English but 5$ in French). This only seems to occur when using the argument 'value'.

In JavaScript, you can get the current user's language by retrieving the translation for the special string "$locale":

var lang = _('$locale'); // en, fr, etc.

== On server side - advanced (PHP) ==

If you want to use translation system in your custom static modules, you will first need to expose the _() function :
<pre>
class mygame extends Table {
// Exposing protected method translation
public static function totranslate($text) {
return self::_($text);
}
}
</pre>

Then you'll be able to use this directly in other modules by doing
<pre>
throw new BgaUserException(mygame::totranslate("Translated error from my awesome module file"));
</pre>

Notice how the "totranslate" is also used by the static analysis to detect your string. So the following will not work :
<pre>
$msg = "Translated error from my awesome module file";
throw new BgaUserException(mygame::totranslate($msg));
</pre>

== Preview another language ==

Once a game is released, you can view a table as a specific language by appending a language code to the URL, such as <pre>&lang=es</pre>

== Analyze your project ==

It looks super complex but there is help!
On studio control panel you can find a button "Check project" - it runs bunch of static analysis on your project including scanning for bad translations and missing translations.
It also will extact all you translation keys as translator will see them so you can double check - and run spell checker on them.

== Other Useful Links ==

* BLOG post about translations https://bga-devs.github.io/blog/posts/translations-summary/

[[Category:Studio]]

Main game logic: Game.php

2024-09-18T17:55:40Z

Sguzzer Gunayer: /* Actions (autowired) */

{{Studio_Framework_Navigation}}

This is the main file for your game logic. Here you initialize the game, persist data, implement the rules and notify the client interface of changes.

This is the main class that implements the "server" callbacks. As it is a server it cannot initiate any data communicate with the game client (running in browser) and only can respond to client using notifications.

Your php class instance won't be in memory between two callbacks, every time client send a request a new class will be created, constructor will be called and eventually your callback function.

== File Structure ==

The details of how the file is structured are described directly with comments in the code skeleton provided to you.

Here is the basic structure:

* '''__construct''': the game constructor, where you define global variables and initiaze class members.
* '''setupNewGame''': initial setup of the game. Takes an array of players, indexed by player_id. Structure of each player includes player_name, player_canal, player_avatar, and flags indicating admin/ai/premium/order/language/beginner.
* '''getAllDatas''': where you retrieve all game data during a complete reload of the game. Return value must be associative array. Value of 'players' is reserved for returning players data from players table, if you set it it must follow certain rules
$result ['players'] = $this->getCollectionFromDb("SELECT player_id id, player_score score, player_no no, player_color color FROM player");
// Returned value must include ['players'][$player_id]]['score'] for scores to populate when F5 is pressed.
* '''getGameProgression''': where you compute the game progression indicator. Returns a number indicating percent of progression (0-100). Used to calculate ELO changes of remaining players when a player quits, or as a conceding requirement (in non-tournament 2 player games, a player may concede if the progression is at least 50%).
* Utility functions: your utility functions.
* Player actions: the entry points for players actions ([https://en.doc.boardgamearena.com/Players_actions:_yourgamename.action.php more info here]).
* Game state arguments: methods to return additional data on specific game states ([http://en.doc.boardgamearena.com/Your_game_state_machine:_states.inc.php#args more info here]).
* Game state actions: the logic to run when entering a new game state ([http://en.doc.boardgamearena.com/Your_game_state_machine:_states.inc.php#action more info here]).
* '''initTable''': (not part of template) - this function is called for every php callback by the framework and it can be implement by the game (empty by default). You can use it in rare cases where you need to read database and manipulate some data before any ANY php entry functions are called (such as getAllDatas,action*,st*, etc). Note: it is not called before arg* methods
* '''zombieTurn''': what to do it's the turn of a zombie player.
* '''upgradeTableDb''': function to migrate database if you change it after release on production.
* '''getGameName''': returns the game name. This will be setup when you create the project. If you are copying files in from another project, make sure you keep this function intact. It must return the right game name, or lots of things will be broken.

== Accessing player information ==

'''Important''': In the following methods, be mindful of the difference between the "active" player and the "current" player. The '''active''' player is the player whose turn it is - not necessarily the player who sent a request! The '''current''' player is the player who sent the request and will see the results returned by your methods: not necessarily the player whose turn it is!

; getPlayersNumber()
: Returns the number of players playing at the table
: Note: doesn't work in the beggining of setupNewGame (use count($players) instead). It will work after initialization of player table.

; getActivePlayerId()
: Get the "active_player", whatever what is the current state type.
: Note: it does NOT mean that this player is active right now, because state type could be "game" or "multiplayer"
: Note: avoid using this method in a "multiplayer" state because it does not mean anything.

; getActivePlayerName()
: Get the "active_player" name
: Note: avoid using this method in a "multiplayer" state because it does not mean anything.

; getPlayerNameById($player_id)
: Get the name by id

; getPlayerColorById($player_id)
: Get the color by id

; getPlayerNoById($player_id)
: Get 'player_no' (number) by id

; loadPlayersBasicInfos()
: Get an associative array with generic data about players (ie: not game specific data).
: The key of the associative array is the player id. The returned table is cached, so ok to call multiple times without performance concerns.
: The content of each value is:
: * player_name - the name of the player
: * player_color (ex: ff0000) - the color code of the player (as string)
: * player_no - the position of the player at the start of the game in natural table order, i.e. 1,2,3

<pre>
$players = $this->loadPlayersBasicInfos();
foreach ($players as $player_id => $info) {
$player_color = $info['player_color'];
...
}
</pre>
Note: if you want array of player ids only you can do this:
$player_ids = array_keys($this->loadPlayersBasicInfos());

; getCurrentPlayerId(bool $bReturnNullIfNotLogged = false) int
: Get the "current_player". The current player is the one from which the action originated (the one who sent the request).
: '''Be careful''': This is not necessarily the active player!
: In general, you shouldn't use this method, unless you are in "multiplayer" state.
: '''Very important''': in your setupNewGame and zombieTurn function, you must never use getCurrentPlayerId() or getCurrentPlayerName(),
: otherwise it will fail with a "Not logged" error message (these actions are triggered from the main site and propagated to the gameserver from a server, not from a browser. As a consequence, there is no current player associated to these actions).

; getCurrentPlayerName(bool $bReturnEmptyIfNotLogged = false) string
: Get the "current_player" name.
: Note: this will throw an exception if current player is not at the table, i.e. spectator
: Be careful using this method (see above).

; getCurrentPlayerColor()
: Get the "current_player" color.
: Note: this will throw an exception if current player is not at the table, i.e. spectator
: Be careful using this method (see above).

; isCurrentPlayerZombie()
: Check the "current_player" zombie status. If true, player is zombie, i.e. left or was kicked out of the game.
: Note: this will throw an exception if current player is not at the table, i.e. spectator

; isSpectator()
: Check the "current_player" spectator status. If true, the user accessing the game is a spectator (not part of the game). For this user, the interface should display all public information, and no private information (like a friend sitting at the same table as players and just spectating the game).

; getActivePlayerColor()
: This function does not seems to exist in API, if you need it here is implementation
function getActivePlayerColor() {
$player_id = $this->getActivePlayerId();
$players = $this->loadPlayersBasicInfos();
if (isset($players[$player_id]))
return $players[$player_id]['player_color'];
else
return null;
}
; isPlayerZombie($player_id)
: This method does not exists, but if you need it it looks like this
protected function isPlayerZombie($player_id) {
$players = $this->loadPlayersBasicInfos();
if (! isset($players[$player_id]))
throw new BgaSystemException("Player $player_id is not playing here");

return ($players[$player_id]['player_zombie'] == 1);
}

== Accessing the database ==

The main game logic should be the only point from which you should access the game database. You access your database using SQL queries with the methods below.

'''IMPORTANT'''

BGA uses [http://dev.mysql.com/doc/refman/5.0/en/sql-syntax-transactions.html database transactions]. This means that your database changes WON'T BE APPLIED to the database until your request ends normally (web request, not database request). Using transactions is in fact very useful for you; at any time, if your game logic detects that something is wrong (example: a disallowed move), you just have to throw an exception and all changes to the game situation will be removed. This also means that you need not (and in fact cannot) use your own transactions for multiple related database operations.

However there are sets of database operation that will do implicit commit (most common mistake is to use "TRUNCATE"), you cannot use these operations during the game, it breaks the unrolling of transactions and will lead to nasty issues
(https://mariadb.com/kb/en/sql-statements-that-cause-an-implicit-commit).

All methods below are part of game class (and view class) and can be accessed using $this->

; DbQuery( string $sql )
: This is the generic method to access the database.
: It can execute any type of SELECT/UPDATE/DELETE/REPLACE/INSERT query on the database. Returns result of the query.
: For SELECT queries, the specialized methods below are much better.
: Do not use method for TRUNCATE, DROP and other table altering operations. See disclamer above about implicit commits. If you really need TRUNCATE use DELETE FROM xxx instead.

; getUniqueValueFromDB( string $sql )
: Returns a unique value from DB or null if no value is found.
: $sql must be a SELECT query.
: Raise an exception if more than 1 row is returned.

; getCollectionFromDB( string $sql, bool $bSingleValue=false ) array
: Returns an associative array of rows for a sql SELECT query.
: The key of the resulting associative array is the first field specified in the SELECT query.
: The value of the resulting associative array is an associative array with all the field specified in the SELECT query and associated values.
: First column must be a primary or alternate key (semantically, it does not actually have to declared in sql as such).
: The resulting collection can be empty (it won't be null).
: If you specified $bSingleValue=true and if your SQL query requests 2 fields A and B, the method returns an associative array "A=>B", otherwise its A=>[A,B]
: Note: The name a bit misleading, it really return associative array, i.e. map and NOT a collection. You cannot use it to get list of values which may have duplicates (hence primary key requirement on first column). If you need simple array use getObjectListFromDB() method.

Example 1:
<pre>
$result = $this->getCollectionFromDB( "SELECT player_id id, player_name name, player_score score FROM player" );

Result:
[
1234 => [ 'id'=>1234, 'name'=>'myuser0', 'score'=>1 ],
1235 => [ 'id'=>1235, 'name'=>'myuser1', 'score'=>0 ]
]
</pre>

Example 2:
<pre>
$result = $this->getCollectionFromDB( "SELECT player_id id, player_name name FROM player", true );

Result:
[
1234 => 'myuser0',
1235 => 'myuser1'
]

</pre>

; getNonEmptyCollectionFromDB(string $sql) array
: Same as getCollectionFromDB($sdl), but raise an exception if the collection is empty. Note: this function does NOT have 2nd argument as previous one does.

; getObjectFromDB(string $sql) array
: Returns one row for the sql SELECT query as an associative array or null if there is no result (where fields are keys mapped to values)
: Raise an exception if the query return more than one row (you can use LIMIT 1 in the query to avoid the exception)

Example:
<pre>
$result = $this->getObjectFromDB( "SELECT player_id id, player_name name, player_score score FROM player WHERE player_id='$player_id'" );

Result:
[
'id'=>1234, 'name'=>'myuser0', 'score'=>1
]
</pre>

; getNonEmptyObjectFromDB(string $sql) array
: Similar to previous one, but raise an exception if no row is found

; getObjectListFromDB(string $sql, bool $bUniqueValue=false) array
: Return an array of rows for a sql SELECT query.
: The result is the same as "getCollectionFromDB" except that the result is a simple array (and not an associative array).
: The result can be empty.
: If you specified $bUniqueValue=true and if your SQL query request 1 field, the method returns directly an array of values.

Example 1:
<pre>
$result = $this->getObjectListFromDB( "SELECT player_id id, player_name name, player_score score FROM player" );

Result:
[
[ 'id'=>1234, 'name'=>'myuser0', 'score'=>1 ],
[ 'id'=>1235, 'name'=>'myuser1', 'score'=>0 ]
]
</pre>

Example 2:
<pre>
$result = $this->getObjectListFromDB( "SELECT player_name name FROM player", true );

Result:
[
'myuser0',
'myuser1'
]

</pre>

; getDoubleKeyCollectionFromDB(string $sql, bool $bSingleValue=false) array
: Return an associative array of associative array, from a SQL SELECT query.
: First array level correspond to first column specified in SQL query.
: Second array level correspond to second column specified in SQL query.
: If $bSingleValue = true, keep only third column on result

; DbGetLastId()
: Return the PRIMARY key of the last inserted row (see PHP mysql_insert_id function).

; DbAffectedRow() int
: Return the number of row affected by the last operation

; escapeStringForDB(string $string) string
: You must use this function on every string type data in your database that contains unsafe data.
: (unsafe = can be modified by a player).
: This method makes sure that no SQL injection will be done through the string used.
: Note: if you using standard types in ajax actions, like AT_alphanum it is sanitized before arrival,
: this is only needed if you manage to get unchecked string, like in the games where user has to enter text as a response.

<pre>

</pre>

Note: see Editing [[Game database model: dbmodel.sql]] to know how to define your database model.

== Use globals ==
Sometimes, you want a single global value for your game, and you don't want to create a DB table specifically for it.

You can do this with the BGA framework "globals". Your value will be stored in the "bga_globals" table in the database, and you can access it with simple methods.

The keys are strings, so you might want to store them in constants to avoid mistakes (the key must be at maximum 50 characters long).

The variable can be of any type (number, string, array, object) and will be stored as a JSON (so functions cannot be stored, and circular references on objects will trigger an Exception when storing).

Having a string key and a JSON serialization allows you to debug easily by looking at the bga_globals table content.

''Note: this globals module doesn't use cache, so every call to one of the following methods makes a DB request.''

'''globals->set(string $name, $mixed $obj): void'''

Define the value of a global variable.
<pre>
const FIRST_PLAYER_ID = "firstPlayerId";
$this->globals->set(FIRST_PLAYER_ID, array_keys($players)[0]);
</pre>

'''globals->get(string $name, $mixed $defaultValue = null): mixed'''

Get the value of a global variable. Returns `null` if not set, except specified otherwise in the optional `$defaultValue`.
<pre>
$currentFirstPlayerId = $this->globals->get(FIRST_PLAYER_ID);
...
$selectedCardsIds = $this->globals->get(SELECTED_CARDS_IDS, []);
</pre>

'''globals->getAll(...$names): array'''

Get the value of all global variables, as a key=>value array. You can set a list of names to only get matching variables. In that case, non-existent keys will not be set in the returned array, so if you have a key with null value, it means the key has been set to null previously.
<pre>
$variables = $this->globals->getAll();
...
$diceVariables = $this->globals->getAll(DIE1, DIE2);
</pre>

Use with PHP's [https://www.php.net/extract extract()] function to quickly assign multiple variables:
<pre>
extract($this->globals->getAll('endTime', 'hour', 'vipWelcome'));
// $endTime, $hour, and $vipWelcome (may) now exist

if (!empty($endTime)) {
...
</pre>

'''globals->delete(...$names): void'''

Delete a global variable or a list of global variables stored in database.
<pre>
$this->globals->delete(SELECTED_CARDS_IDS);
...
$this->globals->delete(SELECTED_CARDS_IDS, UNDO, AFTER_DISCARD_RETURN_STATE);
</pre>

'''globals->has(string $name): bool'''

Indicates if a global variable is stored in database.
<pre>
$cardSelectionIsStarted = $this->globals->has(SELECTED_CARDS_IDS);
</pre>

'''globals->inc(string $name, $int $inc): int'''

Increments the value of a global variable, and return the incremented value. Will trigger an exception if the variable is not a numeric value.
<pre>
$this->globals->inc(PLAYED_ACTIONS_IN_CURRENT_TURN, 1);
...
$totalSpent = $this->globals->inc(SPENT_COINS_IN_CURRENT_TURN, $cardCost);
</pre>

== Use globals (numbers only / game options) ==

Before the `$this->globals`, you could only store numeric values as globals. Theses "GameStateValues" are stored in the "global" table in the database, and you can access it with simple methods.

All methods below are members of the game class and should be accessed via $this->

'''initGameStateLabels(array $labelsMap): void'''

This method should be located at the beginning of constructor of ''yourgamename.game.php''. This is where you define the globals used in your game logic, by assigning them IDs.

You can define up to 80 globals, with IDs from 10 to 89 (inclusive, there can be gaps).
Also you must use this method to access value of game options [[Game_options_and_preferences:_gameoptions.inc.php]], in that case, IDs need to be between 100 and 199.
You must '''not''' use globals outside the range defined above, as those values are used by other components of the framework.

<pre>
function __construct() {
parent::__construct();
$this->initGameStateLabels([
"my_first_global_variable" => 10,
"my_second_global_variable" => 11,
"my_game_variant" => 100
]);
// other code ...
}
</pre>

NOTE: The methods below WILL throw an exception if label is not defined using the call above.

'''setGameStateInitialValue( string $label, int $value ): void'''

Initialize global value. This is not required if you ok with default value if 0. This should be called from setupNewGame function.

'''getGameStateValue( string $label, int $default = 0): int'''

Retrieve the value of a global. Returns $default if global is not been initialized (by setGameStateInitialValue).

NOTE: this method use globals "cache" if you directly manipulated globals table OR call this function after undoRestorePoint() - it won't work as expected.

<pre>
$value = $this->getGameStateValue('my_first_global_variable');
</pre>

For debugging purposes, you can have labels and value pairs send to client side by inserting that code in your "getAllDatas":

<pre>
$labels = array_keys($this->mygamestatelabels);
$result['myglobals'] = array_combine($labels, array_map([$this,'getGameStateValue'],$labels));
</pre>

That assumes you stored your label mapping in $this->mygamestatelabels in constructor
<pre>
$this->mygamestatelabels=["my_first_global_variable" => 10, ...];
$this->initGameStateLabels($this->mygamestatelabels);
</pre>

'''setGameStateValue( string $label, int $value ): void'''

Set the current value of a global.
<pre>
$this->setGameStateValue('my_first_global_variable', 42);
</pre>

'''incGameStateValue( string $label, int $increment ): int'''

Increment the current value of a global. If increment is negative, decrement the value of the global.

Return the final value of the global. If global was not initialized it will initialize it as 0.

NOTE: this method use globals "cache" if you directly manipulated globals table OR call this function after undoRestorePoint() - it won't work as expected.

<pre>
$value = $this->incGameStateValue('my_first_global_variable', 1);
</pre>

=== BGA predefined globals ===

BGA already defines some globals in the ''global'' database table. You should not change them directly but it can be useful to know what they mean when debugging:

{| class="wikitable"
|-
! global_id !! label !! Meaning
|-
| 1 || || Current state
|-
| 2 || || Active player id
|-
| 3 || next_move_id || Next move number
|-
| 4 || || Game id
|-
| 5 || || Table creator id
|-
| 6 || playerturn_nbr || Player turn number
|-
| 7 || gameprogression || Game progression
|-
| 8 || initial_reflexion_time || Initial reflection time
|-
| 9 || additional_reflexion_time || Additional reflection time
|-
| 200 || reflexion_time_profile || Game speed
Real-time games:
* 0 = Real-time • Fast paced
* 1 = Real-time • Normal speed
* 2 = Real-time • Slow speed
* 9 = No time limit • with friends only

Turn-based games:
* 10 = Fast Turn-based • 24 moves per day
* 11 = Fast Turn-based • 12 moves per day
* 12 = Fast Turn-based • 8 moves per day
* 13 = Turn-based • 4 moves per day
* 14 = Turn-based • 3 moves per day
* 15 = Turn-based • 2 moves per day
* 17 = Turn-based • 1 move per day
* 19 = Turn-based • 1 move per 2 days
* 20 = No time limit • with friends only
|-
| 201 || bgaranking_mode || Game mode
* 0 = Normal mode
* 1 = Friendly mode (no ELO)
* 2 = Arena mode
|-
| 207 || game_language ||GAMESTATE_GAME_LANG
|-
| 300 || game_db_version ||GAMESTATE_GAMEVERSION: Current version of the game (when in production)
|-
| 301 || game_result_neutralized ||GAMESTATE_GAME_RESULT_NEUTRALIZED
|-
| 302 || neutralized_player_id ||GAMESTATE_NEUTRALIZED_PLAYER_ID
|-
| 304 || undo_moves_stored ||GAMESTATE_UNDO_MOVES_STORED
|-
| 305 || undo_moves_player ||GAMESTATE_UNDO_MOVES_PLAYER
|-
| 306 || lock_screen_timestamp ||GAMESTATE_LOCK_TIMESTAMP
|}

== Game states and active players ==

=== Activate player handling ===

; $this->activeNextPlayer()
: Make the next player active in the natural player order.
: Note: you CANNOT use this method in a "activeplayer" or "multipleactiveplayer" state. You must use a "game" type game state for this.

; $this->activePrevPlayer()
: Make the previous player active (in the natural player order).
: Note: you CANNOT use this method in a "activeplayer" or "multipleactiveplayer" state. You must use a "game" type game state for this.

; $this->gamestate->changeActivePlayer( $player_id )
: You can call this method to make any player active.
: Note: you CANNOT use this method in a "activeplayer" or "multipleactiveplayer" state. You must use a "game" type game state for this.

; $this->getActivePlayerId()
: Return the "active_player" id
: Note: it does NOT mean that this player is active right now, because state type could be "game" or "multipleactiveplayer"
: Note: avoid using this method in a "multipleactiveplayer" state because it does not mean anything.

=== Multiple activate player handling ===

; $this->gamestate->setAllPlayersMultiactive()
: All playing players are made active. Update notification is sent to all players (this will trigger '''onUpdateActionButtons''').
: Usually, you use this method at the beginning of a game state (e.g., "stGameState") which transitions to a ''multipleactiveplayer'' state in which multiple players have to perform some action. Do not use this method if you going to make some more changes in the active player list. (I.e., if you want to take away multipleactiveplayer status immediately afterwards, use setPlayersMultiactive instead.)

Example of usage:
<pre>
function st_MultiPlayerInit() {
$this->gamestate->setAllPlayersMultiactive();
}
</pre>

; $this->stMakeEveryoneActive()
:this method can be used in state machine to make everybody active as "st" method of multiplayeractive state, it just calls $this->gamestate->setAllPlayersMultiactive()

This is to be used in state declaration:
<pre>
2 => array(
"name" => "playerTurnPlace",
"description" => clienttranslate('Other player must place ships'),
"descriptionmyturn" => clienttranslate('${you} must place ships (click on YOUR SHIPS board to place)'),
"type" => "multipleactiveplayer",
'action' => 'stMakeEveryoneActive',
'args' => 'arg_playerTurnPlace',
"possibleactions" => array( "actionBla" ),
"transitions" => array( "next" => 4, "last" => 99)
),
</pre>

; $this->gamestate->setAllPlayersNonMultiactive( $next_state )
: All playing players are made inactive. Transition to next state

; $this->gamestate->setPlayersMultiactive( $players, $next_state, $bExclusive = false )
: Make a specific list of players active during a multiactive gamestate. Update notification is sent to all players whose state changed.
: "players" is the array of player id that should be made active. If "players" is not empty the value of "next_state" will be ignored (you can put whatever you want)
: If "bExclusive" parameter is not set or false it doesn't deactivate other previously active players. If its set to true, the players who will be multiactive at the end are only these in "$players" array

: In case "players" is empty, the method trigger the "next_state" transition to go to the next game state.
: returns true if state transition happened, false otherwise

; $this->gamestate->setPlayerNonMultiactive( $player_id, $next_state )
: During a multiactive game state, make the specified player inactive.
: Usually, you call this method during a multiactive game state after a player did his action. It is also possible to call it directly from multiplayer action handler.
: If this player was the last active player, the method trigger the "next_state" transition to go to the next game state.
: returns true if state transition happened, false otherwise
Example of usage (see state declaration of playerTurnPlace above):
<pre>
function actionBla($args) {
$this->checkAction('actionBla');
// handle the action using $this->getCurrentPlayerId()
$this->gamestate->setPlayerNonMultiactive( $this->getCurrentPlayerId(), 'next');
}
</pre>

; $this->gamestate->getActivePlayerList()
: With this method you can retrieve the list of the active player at any time.
: During a "game" type gamestate, it will return a void array.
: During a "activeplayer" type gamestate, it will return an array with one value (the active player id).
: During a "multipleactiveplayer" type gamestate, it will return an array of the active players id.
: Note: you should only use this method in the latter case.

; $this->gamestate->updateMultiactiveOrNextState( $next_state_if_none )
: Sends update notification about multiplayer changes. All multiactive set* functions above do that, however if you want to change state manually using db queries for complex calculations, you have to call this yourself after. Do not call this if you calling one of the other setters above.
Example: you have player teams and you want to activate all players in one team
<pre>
$sql = "UPDATE player SET player_is_multiactive='0'";
$this->DbQuery( $sql );
$sql = "UPDATE player SET player_is_multiactive='1' WHERE player_id='$player_id' AND player_team='$team_no'";
$this->DbQuery( $sql );

$this->gamestate->updateMultiactiveOrNextState( 'error' );
</pre>

; updating database manually
: Use this helper function to change multiactive state without sending notification
<pre>
/**
* Changes values of multiactivity in db, does not sent notifications.
* To send notifications after use updateMultiactiveOrNextState
* @param number $player_id, player id <=0 or null - means ALL
* @param number $value - 1 multiactive, 0 non multiactive
*/
function dbSetPlayerMultiactive($player_id = -1, $value = 1) {
if (! $value)
$value = 0;
else
$value = 1;
$sql = "UPDATE player SET player_is_multiactive = '$value' WHERE player_zombie = 0 and player_eliminated = 0";
if ($player_id > 0) {
$sql .= " AND player_id = $player_id";
}
$this->DbQuery($sql);
}
</pre>

;$this->gamestate->isPlayerActive($player_id)
:Return true if specified player is active right now.
:This method take into account game state type, ie nobody is active if game state is "game" and several players can be active if game state is "multiplayer"

;$this->bIndependantMultiactiveTable
:This flag can be set to true in constructor of game.php to force creation of second table to handle multiplayer states (normally these are in player table), this is very advanced feature.
:ONLY use it after you deploy you game to production if you receive unusual amount of bug report with dead lock symptoms DURING multiactiveplayer states
function __construct() {
...
$this->bIndependantMultiactiveTable=true;
}

=== States functions ===
; $this->gamestate->nextState( $transition )
: Change current state to a new state. Important: the $transition parameter is the name of the transition, and NOT the name of the target game state, see [[Your game state machine: states.inc.php]] for more information about states.

'''$this->gamestate->jumpToState($stateNum)'''
: Change current state to a new state. Important: the $stateNum parameter is the key of the state. See [[Your game state machine: states.inc.php]] for more information about states.
: Note: this is very advanced method, it should not be used in normal cases. Specific advanced cases include - jumping to specific state from "do_anytime" actions, jumping to dispatcher state or jumping to recovery state from zombie player function

; $this->checkAction( $actionName, $bThrowException=true )
: Check if the current player can perform a specific action in the current game state, and optionally throw an exception if they can't.
: The action is valid if it is listed in the "possibleactions" array for the current game state (see game state description).
: This method MUST be the first one called in ALL your PHP methods that handle player actions that are not using [[Main game logic: yourgamename.game.php#Actions (autowired)|Action autowiring]], in order to make sure a player doesn't perform an action not allowed by the rules at the point in the game. It should not be called from methods where the current player is not necessarily the active player, otherwise it may fail with an "It is not your turn" exception.
: If "bThrowException" is set to "false", the function returns '''false''' in case of failure instead of throwing an exception. This is useful when several actions are possible, in order to test each of them without throwing exceptions.

; $this->gamestate->checkPossibleAction( $action )
: (rarely used)
: This works exactly like "checkAction" (above), except that it does NOT check if the current player is active.
: '''Note: This does NOT check either spectator or eliminated status, so those checks must be done manually.'''
: This is used specifically in certain game states when you want to authorize additional actions for players that are not active at the moment.
: Example: in ''Libertalia'', you want to authorize players to change their mind about the card played. They are of course not active at the time they change their mind, so you cannot use "checkAction"; use "checkPossibleAction" instead.

This is how PHP action looks that returns player to active state (only for multiplayeractive states). To be able to execute this on client do not call checkAction on js side for this specific action.

function actionUnpass() {
$this->gamestate->checkPossibleAction('actUnpass'); // player changed mind about passing while others were thinking
$this->gamestate->setPlayersMultiactive(array ($this->getCurrentPlayerId() ), 'error', false);
}

; $this->gamestate->state()
: Get an associative array of current game state attributes, see [[Your game state machine: states.inc.php]] for state attributes.

$state=$this->gamestate->state(); if( $state['name'] == 'myGameState' ) {...}

I suggest to define and use this function in your php class to access state name:

public function getStateName() {
$state = $this->gamestate->state();
return $state['name'];
}

; $this->gamestate->state_id()
: Get the id of the current game state (rarely useful, its best to use name, unless you use constants for state ids)

; $this->gamestate->isMutiactiveState()
: Return true if we are in multipleactiveplayer state, false otherwise

=== Private parallel states ===

See the overview of private parallel states [[Your_game_state_machine:_states.inc.php#Private_parallel_states|here]].

; $this->gamestate->initializePrivateStateForAllActivePlayers()
: All active players in a multiactive state are entering a first private state defined in the master state's initialprivate parameter.
: Every time you need to start a private parallel states you need to call this or similar methods below.
: Note: at least one player needs to be active (see [[#Multiple_activate_player_handling|above]]) and current game state must be a multiactive state with initialprivate parameter defined
: Note: initialprivate parameter of master state should be set to the id of the first private state. This private state needs to be defined in states.php with the type set to 'private'.
: Note: this method is usually preceded with activating some or all players
: Note: initializing private state can run action or args methods of the initial private state

Example of usage:
<pre>
function stStartPlayerTurn() {
// This is usually done in master state action method

$this->gamestate->setAllPlayersMultiactive();
$this->gamestate->initializePrivateStateForAllActivePlayers();

// in some cases you can move immediately some or all players to different private states
if ($someCondition) {
//move all players to different state
$this->gamestate->nextPrivateStateForAllActivePlayers("some_transition");
}

if ($other condition) {
//move single player to different state
$this->gamestate->nextPrivateState($specificPlayerId, "some_transition");
}
}
</pre>

; $this->gamestate->initializePrivateStateForPlayers($playerIds)
: Players with specified ids are entering a first private state defined in the master state initialprivate parameter.
: Same considerations apply as for the method above.

; $this->gamestate->initializePrivateState($playerId)
: Player with the specified id is entering a first private state defined in the master state initialprivate parameter.
: Everytime you need to start a private parallel states you need to call this or similar methods above
: Note: player needs to be active (see [[#Multiple_activate_player_handling|above]]) and current game state must be a multiactive state with initialprivate parameter defined
: Note: initialprivate parameter of master state should be set to the id of the first private state. This private state needs to be defined in states.php with the type set to 'private'.
: Note: this method is usually preceded with activating that player
: Note: initializing private state can run action or args methods of the initial private state

Example of usage:
<pre>
function st_ChangeMind() {
// This player finished his move before, but now decides change something while other players are still active
// We activate the player and initialize his private state
$this->gamestate->setPlayersMultiactive([$this->getCurrentPlayerId()], "");
$this->gamestate->initializePrivateState(this->getCurrentPlayerId());

// It is also possible to move the player to some other specific state immediately
$this->gamestate->nextPrivateState($this->getCurrentPlayerId(), "some_transition");
}
</pre>

; $this->gamestate->nextPrivateStateForAllActivePlayers($transition)
: All active players will transition to next private state by specified transition
: Note: game needs to be in a master state which allows private parallel states
: Note: transition should lead to another private state (i.e. a state with type defined as 'private'
: Note: transition should be defined in private state in which the players currently are.
: Note: this method can run action or args methods of the target state
: Note: this is usually used after initializing the private state to move players to specific private state according to the game logic

Example of usage:
<pre>
function stStartPlayerTurn() {
// This is usually done in master state action method
$this->gamestate->setAllPlayersMultiactive();
$this->gamestate->initializePrivateStateForAllActivePlayers();

if ($specificOption) {
//move all players to different state
$this->gamestate->nextPrivateStateForAllActivePlayers("some_transition");
}
}
</pre>

; $this->gamestate->nextPrivateStateForPlayers($playerIds, $transition)
: Players with specified ids will transition to next private state specified by provided transition.
: Same considerations apply as for the method above.

; $this->gamestate->nextPrivateState($playerId, $transition)
: Player with specified id will transition to next private state specified by provided transition
: Note: game needs to be in a master state which allows private parallel states
: Note: transition should lead to another private state (i.e. a state with type defined as 'private'
: Note: transition should be defined in private state in which the players currently are.
: Note: this method can run action or args methods of the target state for specified player
: Note: this is usually used after some player actions to move to next private state

Example of usage:
<pre>
function actSomeAction() {
$this->checkAction("actSomeAction"); //needs to be defined in the current state
$this->gamestate->nextPrivateState($this->getCurrentPlayerId(), "some_transition");
}
</pre>

; $this->gamestate->unsetPrivateStateForAllPlayers()
: All players private state will be reset to null, which means they will get out of private parallel states and be in a master state like the private states are not used
: Note: game needs to be in a master state which allows private parallel states
: Note: this is usually used to clean up after leaving a master state in which private states were used, but can be used in other cases when we want to exit private parallel states and use a regular multiactive state for all players
: Note: After unseting private state only actions on master state are possible
: Note: Usually it is not necessary to unset private states as they will be initialized to first private state when private states are needed again. Nevertheless it is generally better to clean private state after exiting private parallel states to avoid bugs.

Example of usage:
<pre>
function stNextRound() {
$this->gamestate->unsetPrivateStateForAllPlayers();
}
</pre>

; $this->gamestate->unsetPrivateStateForPlayers($playerIds, $transition)
: For players with specified ids private state will be reset to null, which means they will get out of private parallel states and be in a master state like the private states are not used.
: Same considerations apply as for the method above.

; $this->gamestate->unsetPrivateState($playerId)
: For player with specified id private state will be reset to null, which means they will get out of private parallel states and be in a master state like the private states are not used
: Note: game needs to be in a master state which allows private parallel states
: Note: this is usually used when deactivating player to clean up their parallel state
: Note: After unseting private state only actions on master state are possible
: Note: Usually it is not necessary to unset private state as it will be initialized to first private state when private states are needed again. Nevertheless it is generally better to clean private state when not needed to avoid bugs.

Example of usage:
<pre>
function done() {
$this->gamestate->setPlayerNonMultiactive( $this->getCurrentPlayerId(), "newTurn" );
$this->gamestate->unsetPrivateState($this->getCurrentPlayerId());
}
</pre>

; $this->gamestate->setPrivateState($playerId, $newStateId)
: For player with specified id a new private state would be set
: Note: game needs to be in a master state which allows private parallel states
: Note: this should be rarely used as it doesn't check if the transition is allowed (it doesn't even specifies transition). This can be useful in very complex cases when standard state machine is not adequate (i.e. specific cards can lead to some micro action in various states where defining transitions back and forth can become very tedious.)
: Note: this method can run action or args methods of the target state for specified player

Example of usage:
<pre>
function actSomeAction() {
$this->checkAction("actSomeAction"); //needs to be defined in the current state

if ($playerHaveSpecificCard)
return $this->gamestate->setPrivateState($this->getCurrentPlayerId(), 35);

$this->gamestate->nextPrivateState($this->getCurrentPlayerId(), "some_transition");
}
</pre>

; $this->gamestate->getPrivateState($playerId)
: This return the private state or null if not initialized or not in private state

==== State Arguments in Private parallel states ====

The args method called for private states will have the player_id passed to it, allowing you to customise the arguments returned for that player.

Example of usage:
<pre>
function argMyPrivateState($player_id) {
return array(
'my_data' => $this->getPlayerSpecificData($player_id)
);
}
</pre>

==== Inactive Players ====

During Private Parallel State, active players will be managed by the private state that is current assigned to them.

Inactive players will be managed by the master multipleactiveplayer state, so your client should respond to that state in order to display any status message advising players that they are waiting for others to have their turn, or to add any buttons that allow players to potentially "break in" and become active.

== Actions (autowired) ==
The action function should be prefixed by "act" and match the names specified in the "possibleactions" field on the state file.

If your actions start with "act", they will be autowired, that means you can declare action functions on the game.php file and call them directly from the front (with bgaPerformAction). You don't need to use action.php file anymore. The query param from the front request will be matched with the PHP variable of the same name, and it needs to be properly typed. This works for basic types: int, bool, float, string.

<pre>
public function actPlayCard(int $cardId) { ... }
</pre>
This function can be called from front-side with
<pre>
this.bgaPerformAction('actPlayCard', {
cardId: this.selectedCardId // the "cardId" param match the PHP variable name
});
</pre>

(Note: if you also declare the function in the action.php, it will be used instead of the autowiring)

If you want more complex types like int array or JSON, you'll need to specify it using the Param attributes. Same if the PHP variable name is different from the front query param, or if you want to specify the tests that should be realized on the parameter before calling the function.

=== Possible attributes ===

'''BoolParam(?string $name = null)'''
<pre>
use \Bga\GameFramework\Actions\Types\BoolParam;

...

public function actRaiseBet(#[BoolParam(name: 'raise')] bool $raiseBet)

public function actRaiseBet(#[BoolParam(name: 'raise')] bool $raise) // NOTE: it's the same as actRaiseBet(bool $raise) if PHP var name and param name are the same
</pre>

'''IntParam(?string $name = null, public ?int $min = null, public ?int $max = null)'''
<pre>
use \Bga\GameFramework\Actions\Types\IntParam;

...

public function actPlayCard(#[IntParam(name: 'id')] int $cardId)

public function actSpendGold(#[IntParam(min: 1)] int $gold) // will trigger an exception if param is < 1

public function actPlaceCardOnSpot(int $cardId, #[IntParam(min: 1, max: 5)] int $spot) // will trigger an exception if spot is not in 1 to 5 range
</pre>

'''FloatParam(?string $name = null, public ?int $min = null, public ?int $max = null)'''

Works the same way as IntParam, import is <code>use \Bga\GameFramework\Actions\Types\FloatParam;</code>

'''StringParam(?string $name = null, public ?bool $alphanum = false, public ?bool $alphanum_dash = false, public ?bool $base64 = false, public ?array $enum)'''
<pre>
use \Bga\GameFramework\Actions\Types\StringParam;

...

public function actSubmitWord(#[StringParam(alphanum: true)] string $word) // will trigger an exception if the word is not alphanum

public function actChooseAction(#[StringParam(enum: ['move', 'attack', 'pass'])] string $action) // will trigger an exception if the parameter doesn't match a value in the enum
</pre>
Note: You should do one of the tests of the attribute, or test it yourself on the function, to unsure the user is not sending forbidden characters to the function.

'''IntArrayParam(?string $name = null, public ?int $min = null, public ?int $max = null)'''
<pre>
use \Bga\GameFramework\Actions\Types\IntArrayParam;

...

public function actDiscardCards(#[IntArrayParam] array $ids)

public function actDiscardCards(#[IntArrayParam(min: 2, max 8)] array $ids) // will trigger an exception if the array length is not in the 2 to 8 range. It doesn't check the min/max of the array values!
</pre>

This function can be called from front-side with
<pre>
const selectedCardIds = [8, 12, 25];
this.bgaPerformAction('actDiscardCards', {
ids: selectedCardIds.join(',')
});
</pre>

'''JsonParam(?string $name = null, public ?bool $associative = true, public ?bool $alphanum = true)'''
<pre>
use \Bga\GameFramework\Actions\Types\JsonParam;

...

public function actPlanComplexStuff(#[JsonParam] array $answer) // force conversion to array during PHP json decode
public function actPlanComplexStuff(#[JsonParam(associative: false)] object $answer) // force conversion to object during PHP json decode

public function actPlanComplexStuff(#[JsonParam(associative: null)] mixed $answer) // default PHP json decode
</pre>

=== checkAction ===
The autowiring also triggers the checkAction, so you don't have to call it at the beginning of the function. If you need a function that should not trigger checkAction an action that can be played during someone else turn), you can disable it this way:
<pre>
use \Bga\GameFramework\Actions\CheckAction;

...

#[CheckAction(false)]
public function actSetAutopass(bool $autopass)
</pre>

If you disable checkAction, you probably need to call checkPossibleAction instead at the beginning of your function.

=== act prefix ===
The act prefix needed to activate the autowiring is not just to have some consistency in naming, it's also intended to protect your code. If we let autowired action to any function, a player may do a request to 'setPlayerScore' function, even if you never intended for it to be called front side, and it would allow almost undetectable cheating for anyone reading the code of your game.

== Players turn order ==

When table is created the "natural" player order is assigned to player at random, and stored in "read-only" field "player_no".
If you need to create a custom order you should never change natural order but have a separate data structure.
For example you can alter the players table to add another "custom_order" field, you can use state globals or you can use your natural board database,
to store meeple_color/position_location pair.
BGA currently does not provide any API to create/store custom player order.

'''getNextPlayerTable()'''

Return an associative array which associate each player with the next player around the table.

In addition, key 0 is associated to the first player to play.

Example: if three player with ID 1000, 2000 and 3000 are around the table, in this order, the method returns:
<pre>
array(
1000 => 2000,
2000 => 3000,
3000 => 1000,
0 => 1000
);
</pre>

'''getPrevPlayerTable()'''

Same as above, but the associative array associate the previous player around the table. However there no 0 index here.

'''getPlayerAfter( $player_id )'''

Get player playing after given player in natural playing order.

'''getPlayerBefore( $player_id )'''

Get player playing before given player in natural playing order.

Note: There is no API to modify this order, if you have custom player order you have to maintain it in your database
and have custom function to access it.

'''createNextPlayerTable( $players, $bLoop=true )'''

Using $players array creates a map of current => next as in example from getNextPlayerTable(), however you can use custom order here.
If parmeter $bLoop is set to true then last player will points to first (creaing a loop), false otherwise.
In any case index 0 points to first player (first element of $players array). $players is array of player ids in desired order.

Note: This function '''DOES NOT''' change the order in database, it only creates a map using key/values as descibed.

Example of usage:
<pre>
function getNextPlayerTableCustom() {
$starting = $this->getStartingPlayer(); // custom function to get starting player
$player_ids = $this->getPlayerIdsInOrder($starting); // custom function to create players array starting from starting player
return $this->createNextPlayerTable($player_ids, false); // create next player table in custom order
}
</pre>

<pre>
$table = $this->createNextPlayerTable([3000,2000,1000], false);

will return:
[
3000 => 2000,
2000 => 1000,
1000 => null,
0 => 3000
]
</pre>

== Notifications ==

To understand notifications, please read [http://www.slideshare.net/boardgamearena/the-bga-framework-at-a-glance The BGA Framework at a glance] first.

'''IMPORTANT'''

Notifications are crutial part of BGA framework. Everything players see, all changes which happen on frontend (including setup) are done via notfications.
Some of the are framework notifications and some of them are custom (game specific).
Generally you should not send or handle stanard notifications, except exposed APIs.
Example of standard notifications:
* game setup (first time client connects to game)
* game state change
* active player change
Example of custom notification
* game piece moved
* player scored points

Notifications are queued, i.e. sent at the very end of the action, when it ends normally. It means that if you throw an exception for any reason (i.e: move is not allowed), no notifications will be sent to players.

Notification can be sent from the following functions (and transive calls obviosly):

* action handler (action* in game.php). It is a MUST actually. At least one notificaton must be sent (but it includes state transition which sends it)
* game state transition (st* in game.php)
* setupNewGame (after player tables setup is finished)

Notification cannot be sent from the following:
* .view.php
* .action.php
* material.inc.php
* constructor of .game.php
* arg* methods of .game.php

There are conceptually two types of notification:
* public - sent to all client who are listening - that includes all players in the table and spectators
* private - that can only be sent to a player

The bundle of notifications is sent at the end action considered a single "move" and move counter increases.
If you ONLY sending private notifications during action handling - they will not have associate move_id (to avoid it add simple public notification with empty message).
In rare case if you want to change this behavior, you can apply some hackery described in [[BGA_Studio_Cookbook]]

Note: total notification size is now limited to 128K. It seems a lot, but don't forget that notification are bundled and only send at the end of action which also INCLUDES all game state transitions that follow.

The notifications are handled on JS side by subscribing to notifications (only do it for custom notifications!). See [Game_interface_logic:_yourgamename.js#Notifications]

=== NotifyAllPlayers ===

'''notifyAllPlayers(string $notification_type,string $message,array $notification_args )'''

Send a notification to all players of the game and spectators (public).

* notification_type: A string that defines the type of your notification.

Your game interface Javascript logic will use this to know what is the type of the received notification (and to trigger the corresponding method).

* message: A string that defines what is to be displayed in the game log.

You can use an empty string here (''). In this case, nothing is displayed in the game log.

Unless its empty, use "clienttranslate" method to make sure string is translated.

You can use arguments in your $notification_log string, that refers to values defines in the "$notification_args" argument (see below).
Note: Make sure you only use single quotes ('), otherwise PHP will try to interpolate the variable and will ignore the values in the args array.

* notification_args: The arguments of your notifications, as an associative array.

This array will be transmitted to the game interface logic, in order the game interface can be updated.

Complete notifyAllPlayers example (from "Reversi"):

<pre>
$this->notifyAllPlayers( "playDisc", clienttranslate( '${player_name} plays a disc and turns over ${returned_nbr} disc(s)' ),
array(
'player_id' => $player_id,
'player_name' => self::getActivePlayerName(),
'returned_nbr' => count( $turnedOverDiscs ),
'x' => $x,
'y' => $y
) );
</pre>

You can see in the example above the use of the "clienttranslate" method, and the use of 2 arguments "player_name" and "returned_nbr" in the notification log.

'''Important''': NO private data must be sent with this method, as a cheater could see it even if it is not used explicitly by the game interface logic. If you want to send private information to a player, please use notifyPlayer below.

'''Important''': this array is serialized to be sent to the browsers, and will be saved with the notification to be able to replay the game later. If it is too big, it can make notifications slower / less reliable, and replay archives very big (to the point of failing). So as a general rule, you should send only the minimum of information necessary to update the client interface with no overhead in order to keep the notifications as light as possible.

'''Important''': When the game page is reloaded (i.e. F5 or when loading turn based game) all previous notifications are replayed as history notifications. These notifications do not trigger notification handlers and are used basically to build the game log. Because of that most of the notification arguments (except i18n, player_id and all arguments referenced in the message), are removed from these history notifications. If you need additional arguments in history notifications you can add special field <b>preserve</b> to notification arguments, like this:

<pre>
$this->notifyAllPlayers( "playDisc", clienttranslate( '${player_name} plays a disc and turns over ${returned_nbr} disc(s)' ),
array(
'player_id' => $player_id,
'player_name' => self::getActivePlayerName(),
'returned_nbr' => count( $turnedOverDiscs ),
'x' => $x,
'y' => $y,
'preserve' => [ 'x', 'y' ]
) );
</pre>
In this example, fields x and y will be preserved when replaying history notification at the game load.

NOTE: The ONLY reason 'preserve' is useful if you have custom method to render notifications in game log which changes some text arguments into html (i.e. to insert the images instead of plain text). Do not use preserve "just in case" - it will only bloat the logs and make game load VERY slow.

'''Important''': If both public and private notifications are sent to the same player in the same action (AJAX call), they will initially appear in the log in the order in which they were called, but they are placed into the game log in the following order: All private notifications first, then all public notifications. This means that when the page is refreshed, or when a player loads an asynchronous game, if you have called any public notifications ''before'' the last private notification, they will appear out of order in the log.

==== HTML in Notifications ====

You CAN use some HTML inside your notification log, however it not recommended for many reasons:
* Its bad architecture, ui elements leak into server now you have to manage ui in many places
* If you decided to change something in ui in a future version, old games replay and tutorials may not work, since they use stored notifications (for example if the change occured during the game and later this game is used for tutorial)
* When you read log preview for old games its unreadable (this is log before you enter the game replay, useful for troubleshooting or game analysis)
* Its more data to transfer and store in db
* Its nightmare for translators, at least don't put HTML tags inside the "clienttranslate" method. You can use a notification argument instead, and provide your HTML through this argument.

If you still want to have pretty pictures in the log check this [[BGA_Studio_Cookbook#Inject_images_and_styled_html_in_the_log]].

==== Recursive Notifications ====

If your notification contains some phrases that build programmatically you may need to use recursive notifications. In this case the argument can be not only the string but
an array itself, which contains 'log' and 'args', i.e.

$this->notifyAllPlayers('message',clienttranslate('Game moves ${token_name_rec}'),
['token_name_rec'=>['log'=>'${token_name} #${token_number}',
'args'=> ['token_name'=>clienttranslate('Boo'), 'token_number'=>$number, 'i18n'=>['token_name'] ]
]
]);

==== Excluding some players ====

Sometimes you want to notify all players of a message but not have it appear in the log of specific players (for example, have every player see "Player X draws a card" but have Player X will get a private notification "You draw the Ace of Spades", so you want them not to see the public one).

To send a notification to all players but have some clients ignore it, send it as normal from the server, but implement '''setIgnoreNotificationCheck''' on the client to ignore the message under given conditions. See the [[Game_interface_logic:_yourgamename.js#Ignoring_notifications]] documentation for more details. Note: do not sent private info with such notification, hiding something on client side is not a hacker safe.

==== Using player names ====

The variable for player name must be ${player_name} in order to be highlighted with the player color in the game log, it has to have matching 'player_id' argument in $notification_args. If you want a second player name in the log, name the variable ${player_name2} and $player_id2, etc. For the multiple player case, usage of player_id and player_name is not mandatory i.e. skipping to player_id1 and player_name1 is fine.

Special handling of arguments:
* ${player_name} - this will be wrapped in html and text shown using color of the corresponding player, some colors also have reserved background. This will apply recursively as well.
* ${player_name1}, ${player_name2}, ${player_name3}, etc. work the same as above
In order for this to work you must pass corresponding player_idX AND player_nameX in args i.e.

$this->notifyAllPlayers(
'buyAndPassCard',
clienttranslate('${player_name} buys ${card_name} and passes it to ${player_name2}'),
[
'player_id' => $player1['id'],
'player_name' => $player1['name'],
'player_id2' => $player2['id'],
'player_name2' => $player2['name'],
...
]
);

Note: player_name is not translatable, never add it to i18n array

=== NotifyPlayer ===

'''notifyPlayer(int $player_id, string $notification_type, string $message, $notification_args )'''

Same as above, except that the notification is sent to one player only. The player must be the player at the game table.

This method must be used each time some private information must be transmitted to a player.

Important: the variable for player name must be ${player_name} in order to be highlighted with the player color in the game log. Since its a private notification it may be more appropriate to use "you" insted

$this->notifyPlayer($player_id,'message',clienttranslate('You draw ${card_name}'), [ ... ]);
or
$this->notifyPlayer($player_id,'message',clienttranslate('${player_name} draws ${card_name}'), [ 'player_name' => $this->getPlayerNameById($player_id), ... ]);

Note: Spectators cannot be notified using this method, because their player ID is not available via loadPlayersBasicInfos() or otherwise. You must use notifyAllPlayers() for any notification that spectators should get.

== Randomization ==

A large number of board games rely on random, most often based on dice, cards shuffling, picking some item in a bag, and so on. This is very important to ensure a high level of randomness for each of these situations.

Here's are a list of techniques you should use in these situations, from the best to the worst.

=== Dice and bga_rand ===

'''bga_rand( min, max )'''
This is a BGA framework function that provides you a random number between "min" and "max" (inclusive), using the best available random method available on the system.

This is the preferred function you should use, because we are updating it when a better method is introduced.

As of now, bga_rand is based on the PHP function "random_int", which ensures a cryptographic level of randomness.

In particular, it is '''mandatory''' to use it for all '''dice throw''' (ie: games using other methods for dice throwing will be rejected by BGA during review).

Note: rand() and mt_rand() are deprecated on BGA and should not be used anymore, as their randomness is not as good as "bga_rand".

=== Arrays ===

PHP's [https://www.php.net/array_rand array_rand()] and [https://www.php.net/shuffle shuffle()] functions are not cryptographically secure. Instead, the following code based on PHP's [https://www.php.net/random_int random_int()] provides a better method to choose a random key, value, or slice of an array. (the slice preserves keys)

<pre>
private function getRandomKey(array $array)
{
$size = count($array);
if ($size == 0) {
trigger_error("getRandomKey(): Array is empty", E_USER_WARNING);
return null;
}
$rand = random_int(0, $size - 1);
$slice = array_slice($array, $rand, 1, true);
foreach ($slice as $key => $value) {
return $key;
}
}

private function getRandomValue(array $array)
{
$size = count($array);
if ($size == 0) {
trigger_error("getRandomValue(): Array is empty", E_USER_WARNING);
return null;
}
$rand = random_int(0, $size - 1);
$slice = array_slice($array, $rand, 1, true);
foreach ($slice as $key => $value) {
return $value;
}
}

private function getRandomSlice(array $array, int $count)
{
$size = count($array);
if ($size == 0) {
trigger_error("getRandomSlice(): Array is empty", E_USER_WARNING);
return null;
}
if ($count < 1 || $count > $size) {
trigger_error("getRandomSlice(): Invalid count $count for array with size $size", E_USER_WARNING);
return null;
}
$slice = [];
$randUnique = [];
while (count($randUnique) < $count) {
$rand = random_int(0, $size - 1);
if (array_key_exists($rand, $randUnique)) {
continue;
}
$randUnique[$rand] = true;
$slice += array_slice($array, $rand, 1, true);
}
return $slice;
}
</pre>

=== shuffle and cards shuffling ===

To shuffle items, like a pile of cards, the best way is to use the BGA PHP [[Deck]] component and to use "shuffle" method. This ensures that the best available shuffling method is used, and that if in the future we improve it your game will be up to date.

As of now, the Deck component shuffle method is based on PHP "shuffle" method, which has quite good randomness (even if not as good as bga_rand). In consequence, we accept other shuffling methods during reviews, as long as they are based on PHP "shuffle" function (or similar, like "array_rand").

=== Other methods ===

Mysql "RAND()" function has not enough randomness to be a valid method to get a random element on BGA. This function has been used in some existing games and has given acceptable results, but now it should be avoided and you should use other methods instead.

== Game statistics ==

There are 2 types of statistics:
* a "player" statistic is a statistic associated to a player
* a "table" statistic is a statistic not associated to a player (global statistic for this game).

See [[Game statistics: stats.inc.php]] to see how you define statistics for your game.

'''initStat( $table_or_player, $name, $value, $player_id = null )'''

Create a statistic entry with a default value.

This method must be called for each statistic of your game, in your setupNewGame method.
If you neglect to call this for a statistic, and also do not update the value during the course of a certain game using setStat or incStat, the value of the stat will be undefined rather than 0. This will result in it being ignored at the end of the game, as if it didn't apply to that particular game, and excluded from cumulative statistics. As a consequence - if do not want statistic to be applied, do not init it, or call set or inc on it.

'$table_or_player' must be set to "table" if this is a table statistic, or "player" if this is a player statistic.

'$name' is the name of your statistic, as it has been defined in your stats.inc.php file.

'$value' is the initial value of the statistic. If this is a player statistic and if the player is not specified by "$player_id" argument, the value is set for ALL players.

'''setStat( $value, $name, $player_id = null )'''

Set a statistic $name to $value.

If "$player_id" is not specified, setStat consider it is a TABLE statistic.

If "$player_id" is specified, setStat consider it is a PLAYER statistic.

'''incStat( $delta, $name, $player_id = null )'''

Increment (or decrement) specified statistic value by $delta value. Same behavior as setStat function.

'''getStat( $name, $player_id = null )'''

Return the value of statistic specified by $name. Useful when creating derivative statistics such as average.

== Translations ==

See [[Translations]]

== Manage player scores and Tie breaker ==

=== Normal scoring ===

At the end of the game, players automatically get a rank depending on their score: the player with the biggest score is #1, the player with the second biggest score is #2, and so on...

During the game, you update player's score directly by updating "player_score" field of "player" table in database.

Examples:
<pre>

// +2 points to active player
$this->DbQuery( "UPDATE player SET player_score=player_score+2 WHERE player_id='".self::getActivePlayerId()."'" );

// Set score of active player to 5
$this->DbQuery( "UPDATE player SET player_score=5 WHERE player_id='".self::getActivePlayerId()."'" );

</pre>

Note: don't forget to notify the client side in order the score control can be updated accordingly.

=== Tie breaker ===

Tie breaker is used when two players get the same score at the end of a game.

Tie breaker is using "player_score_aux" field of "player" table. It is updated exactly like the "player_score" field.

Tie breaker score is displayed only for players who are tied at the end of the game. Most of the time, it is not supposed to be displayed explicitly during the game.

When you are using "player_score_aux" functionality, you must describe the formula to use in your gameinfos.inc.php file like this:

<pre>
'tie_breaker_description' => totranslate("Describe here your tie breaker formula"),
</pre>

This description will be used as a tooltip to explain to players how this auxiliary score has been calculated.

See also [https://en.doc.boardgamearena.com/Game_meta-information:_gameinfos.inc.php#Multiple_tie_breaker_management Multiple Tie Breaker Management].

=== Co-operative game ===

To make everyone win/lose together in a full-coop game:

Add the following in gameinfos.inc.php :
'is_coop' => 1, // full cooperative

Assign a score of zero to everyone if it's a loss.
Assign the same score > 0 to everyone if it's a win.

=== Semi-coop ===

If the game is not full-coop, then everyone loses = everyone is tied. I.e. set score to 0 to everybody.

=== Only "winners" and "losers" ===

For some games, there is only a group (or a single) "winner", and everyone else is a "loser", with no "end of game rank" (1st, 2nd, 3rd...).

Examples:
* Coup
* Not Alone
* Werewolves
* Quantum

In this case:
* Set the scores so that the winner has the best score, and the other players have the same (lower) score.
* Add the following lines to gameinfos.inc.php:

<pre>
// If in the game, all losers are equal (no score to rank them or explicit in the rules that losers are not ranked between them), set this to true
// The game end result will display "Winner" for the 1st player and "Loser" for all other players
'losers_not_ranked' => true,
</pre>

Werewolves and Coup are implemented like this, as you can see here:
* https://boardgamearena.com/#!gamepanel?game=werewolves&section=lastresults
* https://boardgamearena.com/#!gamepanel?game=coupcitystate&section=lastresults

Adding this has the following effects:
* On game results for this game, "Winner" or "Loser" is going to appear instead of the usual "1st, 2nd, 3rd, ...".
* When a game is over, the result of the game will be "End of game: Victory" or "End of game: Defeat" depending on the result of the CURRENT player (instead of the usual "Victory of XXX").
* When calculating ELO points, if there is at least one "Loser", no "victorious" player can lose ELO points, and no "losing" player can win ELO point. Usually it may happened because being tie with many players with a low rank is considered as a tie and may cost you points. If losers_not_ranked is set, we prevent this behavior and make sure you only gain/loss ELO when you get the corresponding results.

Important: this SHOULD NOT be used for cooperative games (see is_coop parameter), or for 2 players games (it makes no sense in this case).

=== Solo ===

If game supports solo variant, a negative or zero score means defeat, a positive score means victory.

=== Player elimination ===

In some games, this is useful to eliminate a player from the game in order he/she can start another game without waiting for the current game end.

This case should be rare. Please don't use player elimination feature if some player just has to wait the last 10% of the game for game end. This feature should be used only in games where players are eliminated all along the game (typical examples: "Perudo" or "The Werewolves of Miller's Hollow").

Usage:

* Player to eliminate should NOT be active anymore (preferably use the feature in a "game" type game state).
* In your PHP code:
$this->eliminatePlayer( <player_to_eliminate_id> );
* the player is informed in a dialog box that he no longer have to play and can start another game if he/she wants too (with buttons "stay at this table" "quit table and back to main site"). In any case, the player is free to start & join another table from now.
* When your game is over, all players who have been eliminated before receive a "notification" (the small "!" icon on the top right of the BGA interface) that indicate them that "the game has ended" and invite them to review the game results.

'''Important:''' this should not be used on a player who has already left the game ("zombie") as leaving/being kicked of the game (outside of the scope of the rules) is not the same as being eliminated from the game (according to the rules), except if in the course of the game, the zombie player is eliminated according to the rules.

'''Important:''' When all surviving players are eliminated at the same time BGA framework causes the game to be abandoned automatically.
To circumvent this, the game should leave 1 player not eliminated but change final scores accordingly and end the game.

=== Scoring Helper functions ===

These functions should have been API but they are not, just add them to your php game and use for every game.

// get score
function dbGetScore($player_id) {
return $this->getUniqueValueFromDB("SELECT player_score FROM player WHERE player_id='$player_id'");
}

// set score
function dbSetScore($player_id, $count) {
$this->DbQuery("UPDATE player SET player_score='$count' WHERE player_id='$player_id'");
}

// set aux score (tie breaker)
function dbSetAuxScore($player_id, $score) {
$this->DbQuery("UPDATE player SET player_score_aux=$score WHERE player_id='$player_id'");
}

// increment score (can be negative too)
function dbIncScore($player_id, $inc) {
$count = $this->dbGetScore($player_id);
if ($inc != 0) {
$count += $inc;
$this->dbSetScore($player_id, $count);
}
return $count;
}

== Reflexion time ==

; function giveExtraTime( $player_id, $specific_time=null )
: Give standard extra time to this player.
: Standard extra time depends on the speed of the game (small with "slow" game option, bigger with other options).
: You can also specify an exact time to add, in seconds, with the "specified_time" argument (rarely used).

; function isAsync()
: Returns true if game is turn based, false if it is realtime

== Undo moves ==

Please read our [[BGA Undo policy]] before.

'''Important''': Before using these methods, you must also add the following to your "gameinfos.inc.php" file, otherwise these methods are ineffective:
'db_undo_support' => true

Note: if you deploy undo support after game is in production this will take into effect for new games only, old games will give user an error if user choses Undo action, but otherwise it should not affect them.

; function undoSavepoint( )
: Save the whole game situation inside an "Undo save point".
: There is only ONE undo save point available (see [[BGA Undo policy]]). Cannot use in multiactivate state or in game state where next state is multiactive.
: Note: this function does not actually do anything when it is called, it only raises the flag to store the database AFTER transaction is over. So the actual state will be saved when you exit the function calling it (technically before first queued notification is sent, which matters if you transition to game state not to user state after), this may affect what you end up saving.

; function undoRestorePoint()
: Restore the situation previously saved as an "Undo save point".
: You must make sure that the active player is the same after and before the undoRestorePoint (ie: this is your responsibility to ensure that the player that is active when this method is called is exactly the same than the player that was active when the undoSavePoint method has been called).

function actionUndo() {
$this->checkAction('actionUndo');
$this->undoRestorePoint();
$this->gamestate->nextState('next'); // transition to single player state (i.e. beginning of player actions for this turn)
}

'''Important note''': if you are reading game state variable right after restore (without changing state first) it won't work properly as the global table cache is not automatically refreshed after undoRestorePoint(). So you should either change state immediately to refresh game state values, or use $this->gamestate->reloadState() to refresh the state. If you choose to do the latest, be aware that this will bring the state machine back to the state during which the save point snapshot has been taken using undoSavepoint() (which means your transition you do after has to declared in the state which was saved, not in the state which was active for your actionUndo())

== Managing errors and exceptions ==

Note: when you throw an exception, all database changes and all notifications are cancelled immediately. This way, the game situation that existed before the request is completely restored.

; throw new BgaUserException ( $error_message)
: Base class to notify a user error
: You must throw this exception when a player wants to do something that they are not allowed to do.
: The error message will be shown to the player as a "red message".
: The error message must be translated, make sure you use self::_() or $this->_() here and NOT clientranslate()
: Throwing such an exception is NOT considered a bug, so it is not traced in BGA error logs.

Example from Gomoku:
<pre>
throw new BgaUserException( $this->_("There is already a stone on this intersection, you can't play there") );
</pre>

; throw new BgaVisibleSystemException ( $error_message)
: You must throw this exception when you detect something that is not supposed to happened in your code.
: The error message is shown to the user as an "Unexpected error", in order that he can report it in the forum.
: The error message is logged in BGA error logs. If it happens regularly, we will report it to you.

; throw new BgaSystemException ( $error_message)
: Base class to notify a system exception. The message will be hidden from the user, but show in the logs. Use this if the message contains technical information.
: You shouldn't use this type of exception except if you think the information shown could be critical. Indeed: a generic error message will be shown to the user, so it's going to be difficult for you to see what happened.

== Zombie mode ==

When a player leaves a game for any reason (expelled, quit), he becomes a "zombie player". In this case, the results of the game won't count for statistics, but this is cool if the other players can finish the game anyway. That's why zombie mode exists: allow the other player to finish the game, even if the situation is not ideal.

While developing your zombie mode, keep in mind that:
* Do not refer to the rules, because this situation is not planned by the rules.
* Try to figure that you are playing with your friends and one of them has to leave: how can we finish the game without killing the spirit of the game?
* The idea is NOT to develop an artificial intelligence for the game.
* Do not try to end the game early, even in a two-player game. The zombie is there to allow the game to continue, not to end it. Trying to end the game is not supported by the framework and will likely cause unexpected errors.

Most of the time, the best thing to do when it is zombie player turn is to jump immediately to a state where he is not active anymore. For example, if he is in a game state where he has a choice between playing A and playing B, the best thing to do is NOT to choose A or B, but to pass. So, even if there's no "pass" action in the rules, add a "zombiepass" transitition in your game state and use it.

Each time a zombie player must play, your "zombieTurn" method is called.

Parameters:
* $state: the name of the current game state.
* $active_player: the id of the active player.

Most of the time, your zombieTurn method looks like this:

<pre>
function zombieTurn( $state, $active_player )
{
$statename = $state['name'];

if( $statename == 'myFirstGameState'
|| $statename == 'my2ndGameState'
|| $statename == 'my3rdGameState'
....
)
{
$this->gamestate->nextState( "zombiePass" );
}
else
throw new BgaVisibleSystemException( "Zombie mode not supported at this game state: ".$statename );
}
</pre>

Note that in the example above, all corresponding game state should implement "zombiePass" as a transition.

'''Very important''': your zombie code will be called when the player leaves the game. This action is triggered from the main site and propagated to the gameserver from a server, not from a browser. As a consequence, there is no current player associated to this action. In your zombieTurn function, you must '''never''' use getCurrentPlayerId() or getCurrentPlayerName(), otherwise it will fail with a "Not logged" error message.

== User preferences ==
'''getGameUserPreference(int $playerId, int $prefId): ?int'''

Return the value of a user preference for a player. It will return the value currently selected in the select combo box, in the top-right menu.

== Player color preferences ==

BGA premium users may choose their preferred color for playing. For example, if they are used to play green for every board game, they can select "green" in their BGA preferences page.

Making your game compatible with colors preferences is very easy and requires only 1 line of configuration change:

On your gameinfos.inc.php file, add the following lines :

// Favorite colors support: if set to "true", support attribution of favorite colors based on player's preferences (see reattributeColorsBasedOnPreferences PHP method)
// NB: this parameter is used only to flag games supporting this feature; you must use (or not use) reattributeColorsBasedOnPreferences PHP method to actually enable or disable the feature.
'favorite_colors_support' => true,

Then, on your main <your_game>.game.php file check the code of "setupNewGame". New template already have correct code, but if you editing very old game and it may be absent.

$gameinfos = $this->getGameinfos();
...
if ($gameinfos['favorite_colors_support'])
$this->reattributeColorsBasedOnPreferences($players, $gameinfos['player_colors']); // this should be above reloadPlayersBasicInfos()
$this->reloadPlayersBasicInfos();

The "reattributeColorsBasedOnPreferences" method reattributes all colors, taking into account players color preferences and available colors.

Note that you must update the colors to indicate the colors available for your game.

Some important remarks:
* for some games (i.e. Chess), the color has an influence on a mechanism of the game, most of the time by giving a special advantage to a player (i.e. Starting the game). Color preference mechanism must NOT be used in such a case.
* your logic should NEVER consider that the first player has the color X, that the second player has the color Y, and so on. If this is the case, your game will NOT be compatible with reattributeColorsBasedOnPreferences as this method attribute colors to players based on their preferences and not based as their order at the table.

=== Custom color assignments ===
Some colors don't play nicely with BGA's color difference algorithm. If you receive feedback that colors are not well chosen, you can bypass the BGA algorithm by specifying a map from user preference colors to game colors.

For example, you may wish to assign BGA's blue to your game's baby blue: <code>"0000ff" /* Blue */ => "89CFF0",</code> whereas otherwise, a deep purple might be chosen instead. Just be sure that the assigned colors are also present in the <code>player_colors</code> array passed to <code>reattributeColorsBasedOnPreferences</code>, otherwise the assignment will be ignored.

To do this, implement this method in your <code>X.game.php</code> class.

Note: the user preference colors (the keys in the returned array) should not be modified, or the code may not work as expected. These are the colors players can choose between in their profile.
/**
* Returns an array of user preference colors to game colors.
* Game colors must be among those which are passed to reattributeColorsBasedOnPreferences()
* Each game color can be an array of suitable colors, or a single color:
* [
* // The first available color chosen:
* 'ff0000' => ['990000', 'aa1122'],
* // This color is chosen, if available
* '0000ff' => '000099',
* ]
* If no color can be matched from this array, then the default implementation is used.
*/
function getSpecificColorPairings(): array {
return array(
"ff0000" /* Red */ => null,
"008000" /* Green */ => null,
"0000ff" /* Blue */ => null,
"ffa500" /* Yellow */ => null,
"000000" /* Black */ => null,
"ffffff" /* White */ => null,
"e94190" /* Pink */ => null,
"982fff" /* Purple */ => null,
"72c3b1" /* Cyan */ => null,
"f07f16" /* Orange */ => null,
"bdd002" /* Khaki green */ => null,
"7b7b7b" /* Gray */ => null,
);
}

== Legacy games API ==

For some very specific games ("legacy", "campaign"), you need to keep some informations from a game to another.

This should be an exceptional situation: the legacy API is costing resources on Board Game Arena databases, and is slowing down the game setup process + game end of game process. Please do not use it for things like:
* keeping a player preference/settings (=> player preferences and game options should be used instead)
* keeping a statistics, a score, or a ranking, while it is not planned in the physical board game, or while there is no added value compared to BGA statistics / rankings.

You should use it for:
* legacy games: when some components of the game has been altered in a previous game and should be kept as it is.
* "campaign style" games: when a player is getting a "reward" at the end of a game, and should be able to use it in further games.

Important: you cannot store more than 64k of data (serialized as JSON) per player per game. If you go over 64k, storeLegacyData function is going to FAIL, and there is a risk to create a major bug (= players blocked) in your game. You MUST make sure that no more than 64k of data is used for each player for your game. For example, if you are implementing a "campaign style" game and if you allow a player to start multiple campaign, you must LIMIT the number of different campaign so that the total data size to not go over the limit. We strongly recommend you to use this:

try
{
$this->storeLegacyTeamData( $my_data );
}
catch( feException $e ) // feException is a base class of BgaSystemException and others...
{
if( $e->getCode() == FEX_legacy_size_exceeded )
{
// Do something here to free some space in Legacy data (ex: by removing some variables)
}
else
throw $e;
}

The keys may only contain letters and numbers, underscore seems not to be allowed.

; function storeLegacyData( $player_id, $key, $data, $ttl = 365 )
: Store some data associated with $key for the given user / current game
: In the opposite of all other game data, this data will PERSIST after the end of this table, and can be re-used
: in a future table with the same game.
: IMPORTANT: The only possible place where you can use this method is when the game is over at your table (last game action). Otherwise, there is a risk of conflicts between ongoing games.
: TTL is a time-to-live: the maximum, and default, is 365 days.
: In any way, the total data (= all keys) you can store for a given user+game is 64k (note: data is store serialized as JSON data)
: NOTICE: You can store some persistant data across all tables from your game using the specific player_id 0 which is unused. In such case, it's even more important to manage correctly the size of your data to avoid any exception or issue while storing updated data (ie. you can use this for some kind of leaderbord for solo game or contest)
: Note: This function cannot be called during game setup (will throw an error).

; function retrieveLegacyData( $player_id, $key )
: Get data associated with $key for the current game
: This data is common to ALL tables from the same game for this player, and persist from one table to another.
: Note: calling this function has an important cost => please call it few times (possibly: only ONCE) for each player for 1 game if possible
: Note: you can use '%' in $key to retrieve all keys matching the given patterns

; function removeLegacyData( $player_id, $key )
: Remove some legacy data with the given key
: (useful to free some data to avoid going over 64k)

; function storeLegacyTeamData( $data, $ttl = 365 )
: Same as storeLegacyData, except that it stores some data for the whole team within the current table and does not use a key
: Ie: if players A, B and C are at a table, the legacy data will be saved for future table with (exactly) A, B and C on the table.
: This is useful for games which are intended to be played several time by the same team.
: Note: the data total size is still limited, so you must implement catch the FEX_legacy_size_exceeded exception if it happens

; function retrieveLegacyTeamData()
: Same as retrieveLegacyData, except that it retrieves some data for the whole team within the current table (set by storeLegacyTeamData)

; function removeLegacyTeamData()
: Same as removeLegacyData, except that it retrieves some data for the whole team within the current table (set by storeLegacyTeamData)

== Players text input and moderation ==
This section concerns only games where the players have to write some words to play: games based on words, like "Just one" or "Codenames".

Some players will use your game to write insults or profanities. As this is part of the game and not in the game chat, these words cannot be reported by players and moderated.

If you met the following situation:

* You are asking a player to type a text (word(s) or sentence)
* The player can enter any text (this is not a pre-selection or anything you can control)
* This text is visible by at least one other player

Then, you must use the following method:

'''function logTextForModeration( $player_id, $text )'''

player_id = player who write the text

text = text that has been written

This function will have no visible consequence for your game, but will allow players to report the text to moderators if something happens.

== Language dependent games API ==

This API is used for games that are heavily language dependent. Two most common use cases are:
* Games that have a language dependent component that are not necessarily translatable, typically a list of words. (Think of games like Codenames, Decrypto, Just One...)
* Games with massive communication where players would like to ensure that all participants speak the same language. (Think of games like Werewolf, The Resistance, maybe even dixit...)

If this option is used, the table created will be limited only to users that have specific language in their profile. Player starting the game would be able to chose one of the languages they speak.

There is a new property language_dependency in gameinfos.inc.php which can be set like this:
'language_dependency' => false, //or if the property is missing, the game is not language dependent
'language_dependency' => true, //all players at the table must speak the same language
'language_dependency' => array( 1 => 'en', 2 => 'fr', 3 => 'it' ), //1-based list of supported languages

In the gamename.game.php file, you can get the id of selected language with the method '''getGameLanguage'''.
; function getGameLanguage()
: Returns an index of the selected language as defined in gameinfos.inc.php.

Languages currently available on BGA are:
'ar' => array( 'name' => "العربية", 'code' => 'ar_AE' ), // Arabic
'be' => array( 'name' => "беларуская мова", 'code' => 'be_BY' ), // Belarusian
'bn' => array( 'name' => "বাংলা", 'code' => 'bn_BD' ), // Bengali
'bg' => array( 'name' => "български език", 'code' => 'bg_BG' ), // Bulgarian
'ca' => array( 'name' => "català", 'code' => 'ca_ES' ), // Catalan
'cs' => array( 'name' => "čeština", 'code' => 'cs_CZ' ), // Czech
'da' => array( 'name' => "dansk", 'code' => 'da_DK' ), // Danish
'de' => array( 'name' => "deutsch", 'code' => 'de_DE' ), // German
'el' => array( 'name' => "Ελληνικά", 'code' => 'el_GR' ), // Greek
'en' => array( 'name' => "English", 'code' => 'en_US' ), // English
'es' => array( 'name' => "español", 'code' => 'es_ES' ), // Spanish
'et' => array( 'name' => "eesti keel", 'code' => 'et_EE' ), // Estonian
'fi' => array( 'name' => "suomi", 'code' => 'fi_FI' ), // Finnish
'fr' => array( 'name' => "français", 'code' => 'fr_FR' ), // French
'he' => array( 'name' => "עברית", 'code' => 'he_IL' ), // Hebrew
'hi' => array( 'name' => "हिन्दी", 'code' => 'hi_IN' ), // Hindi
'hr' => array( 'name' => "Hrvatski", 'code' => 'hr_HR' ), // Croatian
'hu' => array( 'name' => "magyar", 'code' => 'hu_HU' ), // Hungarian
'id' => array( 'name' => "Bahasa Indonesia", 'code' => 'id_ID' ), // Indonesian
'ms' => array( 'name' => "Bahasa Malaysia", 'code' => 'ms_MY' ), // Malaysian
'it' => array( 'name' => "italiano", 'code' => 'it_IT' ), // Italian
'ja' => array( 'name' => "日本語", 'code' => 'ja_JP' ), // Japanese
'jv' => array( 'name' => "Basa Jawa", 'code' => 'jv_JV' ), // Javanese
'ko' => array( 'name' => "한국어", 'code' => 'ko_KR' ), // Korean
'lt' => array( 'name' => "lietuvių", 'code' => 'lt_LT' ), // Lithuanian
'lv' => array( 'name' => "latviešu", 'code' => 'lv_LV' ), // Latvian
'nl' => array( 'name' => "nederlands", 'code' => 'nl_NL' ), // Dutch
'no' => array( 'name' => "norsk", 'code' => 'nb_NO' ), // Norwegian
'oc' => array( 'name' => "occitan", 'code' => 'oc_FR' ), // Occitan
'pl' => array( 'name' => "polski", 'code' => 'pl_PL' ), // Polish
'pt' => array( 'name' => "português", 'code' => 'pt_PT' ), // Portuguese
'ro' => array( 'name' => "română", 'code' => 'ro_RO' ), // Romanian
'ru' => array( 'name' => "Русский язык", 'code' => 'ru_RU' ), // Russian
'sk' => array( 'name' => "slovenčina", 'code' => 'sk_SK' ), // Slovak
'sl' => array( 'name' => "slovenščina", 'code' => 'sl_SI' ), // Slovenian
'sr' => array( 'name' => "Српски", 'code' => 'sr_RS' ), // Serbian
'sv' => array( 'name' => "svenska", 'code' => 'sv_SE' ), // Swedish
'tr' => array( 'name' => "Türkçe", 'code' => 'tr_TR' ), // Turkish
'uk' => array( 'name' => "Українська мова", 'code' => 'uk_UA' ), // Ukrainian
'zh' => array( 'name' => "中文 (漢)", 'code' => 'zh_TW' ), // Traditional Chinese (Hong Kong, Macau, Taiwan)
'zh-cn' => array( 'name' => "中文 (汉)", 'code' => 'zh_CN' ), // Simplified Chinese (Mainland China, Singapore)

== Debugging and Tracing ==

To debug php code you can use some tracing functions available from the parent class such as debug, trace, error, warn, dump.

$this->debug("Ahh!");
$this->dump('my_var',$my_var);

See [[Practical_debugging]] section for complete information about debugging interfaces and where to find logs.

== PHP 8 upgrade ==

See [[PHP 8 upgrade]]

[[Category:Studio]]