Board Game Arena - User contributions [en]

BGA Type Safe Template: Reversi

2025-03-03T13:51:49Z

Sean-the-sheep: /* Step 9 - Player Actions */

'''Important note: BGA Type Safe Template is a project created by a developer that is not part of the BGA team. This is currently not officially supported by BGA.'''

''This page was generated from [https://github.com/NevinAF/bga-ts-template/blob/main/docs/tutorials/reversi.md BGA TS Template: Reversi.md]. It is recommended to view this document from the source file. All links will redirect to source documentation, and images will only be included via link.''


= TS Template: Reversi Tutorial =

[https://github.com/NevinAF/bga-ts-template?tab=readme-ov-file#board-game-arena-type-safe-template ''BGA Type Safe Template'']

'''Project Files:''' [[BGA-TS-Template-Reversi]]

This page is a beginner friendly tutorial which mimics the official [https://en.doc.boardgamearena.com/Tutorial_reversi Tutorial Reversi] page, but is more approachable and uses the BGA Type Safe Template. If you are not a new Board Game Arena developer, you may want to follow along with the [https://github.com/NevinAF/bga-ts-template?tab=readme-ov-file#getting-started BGA Type Safe Template: Getting Started] guide for a more concise overview of the template.

<blockquote>All steps are recorded as a git branch so you can track the exact changes that were made, and view the project files from any point in the tutorial.
</blockquote>

https://github.com/NevinAF/bga-ts-template/tree/main/docs/tutorials/img/reversi/reversi_steps_branches.gif 


== Steps 0, 1, 2, 3 ==

Go to [https://github.com/NevinAF/bga-ts-template/blob/main/docs/tutorials/index.md TS Template: Tutorial] for the first four steps of the tutorial. The first four steps for any project are the same. To avoid redundancy, they are not repeated here.


== Step 3.5 - From here on out ==

At this point, your are ready to start developing your game. You can choose to follow any of the tutorials or guides on the [https://en.doc.boardgamearena.com/Main_Page BGA Studio Documentation] to continue.

From this point in the tutorial and on:

* It will be assumed that files are built and synced before running the game in the BGA studio.
* It will be assumed that you do a hard refresh of the client page after making changes.
* It will be assumed that you are using all of the default settings for initializing the typescript template. Adjustments can be made as needed and all sections have links to original file documentation for reference.
* Most steps will have specific instructions, but you can always adjust at your own discretion.

''Make sure the following game information is set for Reversi:''

<pre lang="json">// gameinfos.jsonc
{
"players": [ 2 ],
"bgg_id": 2389,
"player_colors": [ "cbcbcb", "363636" ],
"favorite_colors_support": false
}</pre>

== Step 4 - Game Board ==

# Download the following board image for Reversi, and place it in the <code>img</code> folder of your project. It should be named <code>board.jpg</code> to match the SCSS background-image in the next step.


https://github.com/NevinAF/bga-ts-template/tree/main/docs/tutorials/img/reversi/assets/board.jpg

<ol start="2" style="list-style-type: decimal;">
<li>Add the board to the DOM by adding the following Smarty template code to the <code>yourgamename_yourgamename.tpl</code> file:
<pre lang="html"><div id="board">

<div id="square_{X}_{Y}" class="square" style="left: {LEFT}px; top: {TOP}px;"></div>

</div></pre>
<blockquote>The <code></code> and <code></code> are Smarty template tags that let you programmatically generate HTML as you will use in a following step. See [https://en.doc.boardgamearena.com/Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl X_X.tpl] for more information about the template file for BGA games.</blockquote></li>
<li>Add the following SCSS to the <code>yourgamename.scss</code> file to style the board:
<pre lang="scss">#board {
// Setup Image
width: 536px;
height: 528px;
background-image: url('img/board.jpg');
// Center the board
margin: auto;
left: 0; top: 0; right: 0; bottom: 0;
// Tokens and squares are absolutely placed relative to the board
position: relative;
}

.square {
// Size of a square
width: 62px;
height: 62px;
// Position relative to the board, not affected by other elements.
position: absolute;
// Placeholder for validating the positions.
background-color: red;
}</pre>
<blockquote>See [https://en.doc.boardgamearena.com/Game_interface_stylesheet:_yourgamename.css X.css] for more information about the style sheet for BGA games.</blockquote>

https://github.com/NevinAF/bga-ts-template/tree/main/docs/tutorials/img/reversi/step4-3.png Reloading the game (with a hard refresh).
</li>
<li>Add the following code to the <code>yourgamename.view.php</code> file.
<pre lang="php">// function build_page( $viewArgs ) {
// ...
/*********** Place your code below: ************/

// States that we should start inserting at the 'square' block
// <yourgamename>_<yourgamename> should be replaced with your game name: tstemplatereversi_tstemplatereversi
$this->page->begin_block( "<yourgamename>_<yourgamename>", "square" );

$hor_scale = 64.8; // Constant for square width
$ver_scale = 64.4; // Constant for square height
for( $x=1; $x<=8; $x++ ) // Loop the 8 columns..
{
for( $y=1; $y<=8; $y++ ) // Loop the 8 rows..
{
// Inserts the code found at the square block based on the variables.
$this->page->insert_block( "square", array(
'X' => $x,
'Y' => $y,
'LEFT' => round( ($x-1)*$hor_scale+10 ),
'TOP' => round( ($y-1)*$ver_scale+7 )
) );
}
}</pre>
<blockquote>See [https://en.doc.boardgamearena.com/Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl X.view.php] for more information about the view file for BGA games.</blockquote>

https://github.com/NevinAF/bga-ts-template/tree/main/docs/tutorials/img/reversi/step4-4.png Reloading the game (with a hard refresh).
</li></ol>


== Step 5 - The Tokens ==

<ol style="list-style-type: decimal;">
<li>Add the following token image to the <code>img</code> folder of your project. It should be named <code>tokens.png</code> to match the SCSS background-image in the next step.

https://github.com/NevinAF/bga-ts-template/tree/main/docs/tutorials/img/reversi/assets/tokens.png
</li>
<li>Add a template variable to the <code>yourgamename_yourgamename.tpl</code> file to represent the tokens:
<pre lang="html"><div id="board"> ... </div>

<script type="text/javascript">

var jstpl_token='<div class="token tokencolor_${color}" id="token_${x_y}"></div>';

</script></pre>
<blockquote>Note that this does not have any information that needs to be populated by the server, so this could be directly defined in the TypeScript file.</blockquote></li>
<li>Add the following SCSS to the <code>yourgamename.scss</code> file to style the tokens:
<pre lang="scss">// Same as square, but matching the token size/image.
.token {
width: 56px;
height: 56px;
position: absolute;
background-image: url('img/tokens.png');
}
// For clarity, but doesn't actually do anything.
.tokencolor_cbcbcb { background-position: 0px 0px; }
// Translate the background the exact size of the white token, so the black one shows instead.
.tokencolor_363636 { background-position: -56px 0px; }</pre></li>
<li>Add a TypeScript function to the <code>yourgamename.ts</code> file to place the tokens on the board. You can hover over any function/property in the TypeScript file to see the documentation and usage.
<pre lang="typescript">///////////////////////////////////////////////////
//// Utility methods

/** Adds a token matching the given player to the board at the specified location. */
addTokenOnBoard( x: number, y: number, player_id: number )
{
let player = this.gamedatas.players[ player_id ];
if (!player)
throw new Error( 'Unknown player id: ' + player_id );

dojo.place( this.format_block( 'jstpl_token', {
x_y: `${x}_${y}`,
color: player.color
} ) , 'board' );

this.placeOnObject( `token_${x}_${y}`, `overall_player_board_${player_id}` );
this.slideToObject( `token_${x}_${y}`, `square_${x}_${y}` ).play();
}</pre>
<blockquote>See [https://en.doc.boardgamearena.com/Game_interface_logic:_yourgamename.js X.js] for more information about the script file for BGA games.</blockquote></li>
<li>For a placeholder, test your tokens by manually placing some in the setup function. you can also remove the boilerplate code.:
<pre lang="typescript">///////////////////////////////////////////////////
//// Game setup

setup(gamedatas: Gamedatas): void
{
console.log( "Starting game setup" );

this.addTokenOnBoard( 2, 2, this.player_id );
this.addTokenOnBoard( 6, 3, this.player_id );

this.setupNotifications(); // <-- Keep this line
}</pre>

https://github.com/NevinAF/bga-ts-template/tree/main/docs/tutorials/img/reversi/step5-4.png Reloading the game (with a hard refresh).
</li></ol>


== Step 6 - The Database and Initial Setup ==

<ol style="list-style-type: decimal;">
<li>Create a database for your board in the <code>dbmodel.sql</code> file:
<pre lang="sql">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>
Pay special attention to the backtick <code>`</code> character vs. the single quote <code>'</code> when working with SQL. You can quit and restart your game to see if the file is correct.
<blockquote>See [https://en.doc.boardgamearena.com/Game_database_model:_dbmodel.sql dbmodel.sql] for more information about the database file for BGA games.</blockquote></li>
<li>Setup the board in your <code>yourgamename.game.php</code> file. This is initializing the data in the database and setting the four discs in the center of the board:
<pre lang="php">protected function setupNewGame( $players, $options = array() )
{
//...
$sql .= implode( ',', $values );
self::DbQuery( $sql );
// self::reattributeColorsBasedOnPreferences( $players, $gameinfos['player_colors'] );
self::reloadPlayersBasicInfos();

/************ Start the game initialization *****/
$sql = "INSERT INTO board (board_x,board_y,board_player) VALUES ";
$sql_values = array();
list( $whiteplayer_id, $blackplayer_id ) = array_keys( $players );
for( $x=1; $x<=8; $x++ )
{
for( $y=1; $y<=8; $y++ )
{
// Initial positions of white player
if( ($x==4 && $y==4) || ($x==5 && $y==5) )
$token_value = "'$whiteplayer_id'";
// Initial positions of black player
else if( ($x==4 && $y==5) || ($x==5 && $y==4) )
$token_value = "'$blackplayer_id'";
// Not a starting position
else
$token_value = "NULL";
$sql_values[] = "('$x','$y',$token_value)";
}
}
$sql .= implode( ',', $sql_values );
self::DbQuery( $sql );
//...
}</pre></li>
<li>Now we need to send the board information to the client whenever the page is reloaded. In your <code>yourgamename.game.php</code> file, add the following code to the <code>getAllDatas</code> function:
<pre lang="php">protected function getAllDatas()
{
//...
$sql = "SELECT board_x x, board_y y, board_player player
FROM board WHERE board_player IS NOT NULL";
$result['board'] = self::getObjectListFromDB( $sql );
//...
}</pre></li>
<li>Add the board data to the <code>Gamedatas</code> interface in the <code>yourgamename.d.ts</code> file:
<pre lang="typescript">interface Gamedatas {
board: { x: number, y: number, player: number }[];
}</pre></li>
<li>Add the following to the <code>yourgamename.ts</code> file place the discs at the start of a page load:
<pre lang="typescript">setup(gamedatas: Gamedatas): void
{
console.log( "Starting game setup" );

// Place the tokens on the board
for( let i in gamedatas.board )
{
let square = gamedatas.board[i];

if( square?.player ) // If square is defined and has a player
this.addTokenOnBoard( square.x, square.y, square.player );
}

this.setupNotifications(); // <-- Keep this line
}</pre>

https://github.com/NevinAF/bga-ts-template/tree/main/docs/tutorials/img/reversi/step6-5.png Reloading the game (with a hard refresh).
</li></ol>


== Step 7 - Game States ==

<ol style="list-style-type: decimal;">
<li>Replace the gamestates.jsonc file with the following:
<pre lang="json">{
"$schema": "../../node_modules/bga-ts-template/schema/gamestates.schema.json",

// The initial state. Please do not modify.
"1": {
"name": "gameSetup",
"description": "",
"type": "manager",
"action": "stGameSetup",
"transitions": { "": 10 }
},

"10": {
"name": "playerTurn",
"description": "${actplayer} must play a disc",
"descriptionmyturn": "${you} must play a disc",
"type": "activeplayer",
"args": "argPlayerTurn",
"argsType": {
"possibleMoves": "boolean[][]"
},
"possibleactions": {
"playDisc": [
{ "name": "x", "type": "AT_int" },
{ "name": "y", "type": "AT_int" }
]
},
"transitions": {
"playDisc": 11,
"zombiePass": 11
}
},

"11": {
"name": "nextPlayer",
"type": "game",
"action": "stNextPlayer",
"updateGameProgression": true,
"transitions": {
"nextTurn": 10,
"cantPlay": 11,
"endGame": 99
}
},

// Final state.
// Please do not modify (and do not overload action/args methods}.
"99": {
"name": "gameEnd",
"description": "End of game",
"type": "manager",
"action": "stGameEnd",
"args": "argGameEnd",
"argsType": "object"
}
}</pre>
There is a lot of information in this file. Most information can be found in the hover-over tooltips, but the [https://en.doc.boardgamearena.com/Your_game_state_machine:_states.inc.php Game States] page has more information about the concepts.
<blockquote>This will automatically be converted to <code>gamestates.inc.php</code>, <code>yourgamename.action.php</code>, and <code>build/gamestates.d.ts</code> when you run <code>npm run build</code>.</blockquote></li>
<li>Add placeholder functions to remove <code>Undefined method</code> errors. Add the following to your <code>yourgamename.action.php</code> file. Note that this replaces the large section of comments in the file describing the player actions, state arguments, and state actions.
<pre lang="php">// Player actions
function playDisc( int $x, int $y ) {
/* TODO */
}

// Game state arguments
function argPlayerTurn() {
/* TODO */
}

// Game state actions
function stNextPlayer() {
/* TODO */
}</pre></li>
<li>Fix the <code>dummmy</code> state errors in your <code>yourgamename.ts</code> file. These are added as a placeholder and now cause issues because there is no gamestate with the name <code>dummmy</code>:
<pre lang="typescript">onEnteringState(stateName: GameStateName, args: CurrentStateArgs): void
{
console.log( 'Entering state: ' + stateName );
}

onLeavingState(stateName: GameStateName): void
{
console.log( 'Leaving state: ' + stateName );
}

onUpdateActionButtons(stateName: GameStateName, args: AnyGameStateArgs | null): void
{
console.log( 'onUpdateActionButtons: ' + stateName, args );
}</pre></li></ol>

<blockquote>You should no longer have any type issues in any of your files.
</blockquote>
When you reload your game (this will cause current games to fail), your should see the banner change to <code>{actplayer} must play a disc</code> or <code>You must play a disc</code>. This will be the only visible change in the game at this point.


https://github.com/NevinAF/bga-ts-template/tree/main/docs/tutorials/img/reversi/step7-3.png Reloading the game (with a hard refresh).


== Step 8 - Game Rules and Possible Moves ==

There are a couple of variations on the rules for Reversi, but the most common is with <code>outflanking rules</code>. You can see the official rules at [https://www.worldothello.org/about/about-othello/othello-rules/official-rules/ World Othello]. There rules have been implemented with the following utility functions.

<ol style="list-style-type: decimal;">
<li>Copy these functions into your <code>yourgamename.game.php</code> file:
<pre lang="php">// Get the complete board with a double associative array
function getBoard()
{
$sql = "SELECT board_x x, board_y y, board_player player FROM board";
return self::getDoubleKeyCollectionFromDB( $sql, true );
}

// Get the list of possible moves (x => y => true)
function getPossibleMoves( $player_id )
{
$result = array();

$board = self::getBoard();

for( $x=1; $x<=8; $x++ )
{
for( $y=1; $y<=8; $y++ )
{
$returned = self::getTurnedOverDiscs( $x, $y, $player_id, $board );
if( count( $returned ) == 0 )
{
// No discs returned => not a possible move
}
else
{
// Okay => set this coordinate to "true"
if( ! isset( $result[$x] ) )
$result[$x] = array();

$result[$x][$y] = true;
}
}
}

return $result;
}

// Get the list of returned disc when "player" we play at this place ("x", "y"),
// or a void array if no disc is returned (invalid move)
function getTurnedOverDiscs( $x, $y, $player, $board )
{
$turnedOverDiscs = array();

if( $board[ $x ][ $y ] === null ) // If there is already a disc on this place, this can't be a valid move
{
// For each directions...
$directions = array(
array( -1,-1 ), array( -1,0 ), array( -1, 1 ), array( 0, -1),
array( 0,1 ), array( 1,-1), array( 1,0 ), array( 1, 1 )
);

foreach( $directions as $direction )
{
// Starting from the square we want to place a disc...
$current_x = $x;
$current_y = $y;
$bContinue = true;
$mayBeTurnedOver = array();

while( $bContinue )
{
// Go to the next square in this direction
$current_x += $direction[0];
$current_y += $direction[1];

if( $current_x<1 || $current_x>8 || $current_y<1 || $current_y>8 )
$bContinue = false; // Out of the board => stop here for this direction
else if( $board[ $current_x ][ $current_y ] === null )
$bContinue = false; // An empty square => stop here for this direction
else if( $board[ $current_x ][ $current_y ] != $player )
{
// There is a disc from our opponent on this square
// => add it to the list of the "may be turned over", and continue on this direction
$mayBeTurnedOver[] = array( 'x' => $current_x, 'y' => $current_y );
}
else if( $board[ $current_x ][ $current_y ] == $player )
{
// This is one of our disc

if( count( $mayBeTurnedOver ) == 0 )
{
// There is no disc to be turned over between our 2 discs => stop here for this direction
$bContinue = false;
}
else
{
// We found some disc to be turned over between our 2 discs
// => add them to the result and stop here for this direction
$turnedOverDiscs = array_merge( $turnedOverDiscs, $mayBeTurnedOver );
$bContinue = false;
}
}
}
}
}

return $turnedOverDiscs;
}</pre></li>
<li>Add the list of possible moves to the <code>argPlayerTurn</code> function in your <code>yourgamename.action.php</code> file:
<pre lang="php">function argPlayerTurn()
{
$possibleMoves = self::getPossibleMoves( self::getActivePlayerId() );
return array(
'possibleMoves' => $possibleMoves
);
}</pre></li>
<li>Add a css class to represent the possible moves in your <code>yourgamename.scss</code> file:
<pre lang="scss">.possibleMove {
background-color: rgba(255, 255, 255, 0.15);
cursor: pointer;
transition: 100ms;
}

.possibleMove:hover {
background-color: rgba(255, 255, 255, 0.3);
}</pre></li>
<li>Add the possible moves to the board when entering a new state by adding the following to your <code>yourgamename.ts</code> file:
<pre lang="typescript">// Utility methods

/** Removes the 'possibleMove' class from all elements. */
clearPossibleMoves() {
document.querySelectorAll('.possibleMove').forEach(element => {
element.classList.remove('possibleMove');
});
}

/** Updates the squares on the board matching the possible moves. */
updatePossibleMoves( possibleMoves: boolean[][] )
{
this.clearPossibleMoves();

for( var x in possibleMoves )
{
for( var y in possibleMoves[ x ] )
{
let square = $(`square_${x}_${y}`);
if( !square )
throw new Error( `Unknown square element: ${x}_${y}. Make sure the board grid was set up correctly in the tpl file.` );
square.classList.add('possibleMove');
}
}

this.addTooltipToClass( 'possibleMove', '', _('Place a disc here') );
}

// Game & client states

onEnteringState(stateName: GameStateName, args: CurrentStateArgs): void
{
console.log( 'Entering state: '+stateName );

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

https://github.com/NevinAF/bga-ts-template/tree/main/docs/tutorials/img/reversi/step8-4.png Reloading the game (with a hard refresh).
</li></ol>

The game is still not playable, but you can now see the possible moves for the first turn.


== Step 9 - Player Actions ==

<ol style="list-style-type: decimal;">
<li>Fill in the <code>playDisc</code> function in your <code>yourgamename.action.php</code> file:
<pre lang="php">function playDisc( int $x, int $y )
{
// Check that this player is active and that this action is possible at this moment
self::checkAction( 'playDisc' );

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

if( count( $turnedOverDiscs ) <= 0 )
throw new BgaSystemException( "Impossible move" );

// This move is possible!

// 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') ) ";

self::DbQuery( $sql );

// 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
)";
self::DbQuery( $sql );

// Then, go to the next state
$this->gamestate->nextState( 'playDisc' );
}</pre></li>
<li>Fill in the <code>stNextPlayer</code> function in your <code>yourgamename.action.php</code> file:
<pre lang="php">function stNextPlayer()
{
// Active next player
$player_id = self::activeNextPlayer();

// Check if both player has at least 1 discs, and if there are free squares to play
$sql = "SELECT board_player, COUNT( board_x ) FROM board
GROUP BY board_player";
$player_to_discs = self::getCollectionFromDb( $sql, 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 = self::getPossibleMoves( $player_id );
if( count( $possibleMoves ) == 0 )
{
// This player can't play
// Can his opponent play ?
$opponent_id = self::getUniqueValueFromDb( "SELECT player_id FROM player WHERE player_id!='$player_id' " );
if( count( self::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
self::giveExtraTime( $player_id );
$this->gamestate->nextState( 'nextTurn' );
}
}</pre></li>
<li>Connect an <code>onclick</code> function to all of the squares on the board:
<pre lang="typescript">setup(gamedatas: Gamedatas): void { // … dojo.query( ‘.square’ ).connect( ‘onclick’, this, ‘onPlayDisc’ ); // … }</pre></li>
<li>Add the <code>onPlayDisc</code> function to your <code>yourgamename.ts</code> file:
<pre lang="typescript">// Player's action

/** Called when a square is clicked, check if it is a possible move and send the action to the server. */
onPlayDisc( evt: Event )
{
// Stop this event propagation
evt.preventDefault();

if (!(evt.currentTarget instanceof HTMLElement))
throw new Error('evt.currentTarget is null! Make sure that this function is being connected to a DOM HTMLElement.');

// Check if this is a possible move
if( !evt.currentTarget.classList.contains('possibleMove') )
return;

// Check that this action is possible at this moment (shows error dialog if not possible)
if( !this.checkAction( 'playDisc' ) )
return;

// Get the clicked square x and y
// Note: square id format is "square_X_Y"
let [_square_, x, y] = evt.currentTarget.id.split('_');

this.ajaxcall( `/${this.game_name}/${this.game_name}/playDisc.html`, {
x, y, lock: true
}, this, function() {} );
}</pre></li></ol>

Now you should be able to play the game! However, you will need to reload the game after every move to force the board to update.


== Step 10 - Notifications ==

Notifications are used to inform players when something happens in the game. In our case, we only need to send one notification stating when the player has played a disc; however, it is often much more useful to send the notifications as a sequence of events so they can be automatically sequenced in the client. In this case, we will send three notifications:=, all of which can be sent from the player action function: - When a player plays a disc - When discs are converted because of a move - When the scores

<ol style="list-style-type: decimal;">
<li>Add the following to the <code>playDisc</code> function in your <code>yourgamename.action.php</code> file:
<pre lang="php">function playDisc( int $x, int $y )
{
// ...

// Notify
self::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
) );

self::notifyAllPlayers( "turnOverDiscs", '', array(
'player_id' => $player_id,
'turnedOver' => $turnedOverDiscs
) );

$newScores = self::getCollectionFromDb( "SELECT player_id, player_score FROM player", true );
self::notifyAllPlayers( "newScores", "", array(
"scores" => $newScores
) );

// Then, go to the next state
$this->gamestate->nextState( 'playDisc' );
}</pre></li>
<li>Add the notifications to your <code>NotifTypes</code> interface in the <code>yourgamename.d.ts</code> file:
<pre lang="typescript">interface NotifTypes {
'playDisc': { x: number, y: number, player_id: number };
'turnOverDiscs': {
player_id: number,
turnedOver: { x: number, y: number }[]
},
'newScores': { scores: Record<number, number> };
}</pre></li>
<li>Add the following to your <code>yourgamename.ts</code> file to listen and handle the notifications:
<pre lang="typescript">setupNotifications()
{
console.log( 'notifications subscriptions setup' );

dojo.subscribe( 'playDisc', this, "notif_playDisc" );
this.notifqueue.setSynchronous( 'playDisc', 500 );
dojo.subscribe( 'turnOverDiscs', this, "notif_turnOverDiscs" );
this.notifqueue.setSynchronous( 'turnOverDiscs', 1000 );
dojo.subscribe( 'newScores', this, "notif_newScores" );
this.notifqueue.setSynchronous( 'newScores', 500 );
}

notif_playDisc( notif: NotifAs<'playDisc'> )
{
this.clearPossibleMoves();
this.addTokenOnBoard( notif.args.x, notif.args.y, notif.args.player_id );
}

notif_turnOverDiscs( notif: NotifAs<'turnOverDiscs'> )
{
// Change the color of the turned over discs
for( var i in notif.args.turnedOver )
{
let token_data = notif.args.turnedOver[ i ]!;
let token = $<HTMLElement>( `token_${token_data.x}_${token_data.y}` );

if (!token)
throw new Error( `Unknown token element: ${token_data.x}_${token_data.y}. Make sure the board grid was set up correctly in the tpl file.` );

token.classList.toggle('tokencolor_cbcbcb');
token.classList.toggle('tokencolor_363636');
}
}

notif_newScores( notif: NotifAs<'newScores'> )
{
for( var player_id in notif.args.scores )
{
let counter = this.scoreCtrl[ player_id ];
let newScore = notif.args.scores[ player_id ];
if (counter && newScore)
counter.toValue( newScore );
}
}</pre></li>
<li>(optional) Add a flipping animation to the token when the classes:
''yourgamename_yourgamename.tpl'' <code>html // Updated token template var jstpl_token = '<div class="token-container tokencolor_${color}" id="token_${x_y}"><div class="token-flip"><div class="token-white"></div><div class="token-black"></div></div></div>';</code>
''yourgamename.scss'' ```scss .token-container { background-color: transparent; width: 56px; height: 56px; perspective: 250px; position: absolute; }
.token-flip { position: relative; width: 100%; height: 100%; text-align: center; transition: transform 1.2s; transform-style: preserve-3d; border-radius:50%; box-shadow: 0 4px 8px 0 rgba(0,0,0,0.25); }
.tokencolor_363636 > .token-flip { transform: rotateY(180deg); }
.token-white, .token-black { position: absolute; width: 100%; height: 100%; -webkit-backface-visibility: hidden; backface-visibility: hidden; background-image: url(“img/tokens.png”); }
.token-white { background-position: 0px 0px; }
.token-black { background-position: -56px 0px; transform: rotateY(180deg); } ```

https://github.com/NevinAF/bga-ts-template/tree/main/docs/tutorials/img/reversi/step10-4.gif
</li></ol>

At this point, you now have a fully functional game that can be played on BGA. The following steps are to add flurishes and additional features to the game.


== (optional) Step 11 - Statistics ==

Statistics are mostly optional and are a fun way to compare player strategies or how much they have played the game.

<ol style="list-style-type: decimal;">
<li>Replace the contents of <code>shared/stats.jsonc</code> with the following:
<pre lang="json">{
"$schema": "../../node_modules/bga-ts-template/schema/stats.schema.json",
// All of these stats are tracked per player
"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>
<blockquote>See [https://en.doc.boardgamearena.com/Game_statistics:_stats.json stats.json] for more information about the stats file for BGA games.</blockquote></li>
<li>Add the following to the <code>playDisc</code> function in your <code>yourgamename.action.php</code> file:
<pre lang="php">function playDisc( int $x, int $y )
{
//...
// Update scores...

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

// Notify...
}</pre></li>
<li>Reload the statistics configuration on the manage game page. See [https://github.com/NevinAF/bga-ts-template/blob/main/docs/tutorials/index.md#step-3---game-information--metadata Step 3.3] for more information.

https://github.com/NevinAF/bga-ts-template/tree/main/docs/tutorials/img/reversi/game_configuration.png
</li>
<li>Play a game and verify that your new statistics are visible at the end of the game:

https://github.com/NevinAF/bga-ts-template/tree/main/docs/tutorials/img/reversi/step11-3.png
</li></ol>


== (Optional) Step 12 - Game Options ==

Game options are a way for users to change game behavior or rules. As an example, we will be adding another rule variant called “Reversi Bombs” that flips all 8 adjacent discs when a disc is played.


https://github.com/NevinAF/bga-ts-template/tree/main/docs/tutorials/img/reversi/reversi_bombs_rules.png

<ol style="list-style-type: decimal;">
<li>Replace your gameoptions with the following in the <code>shared/gameoptions.jsonc</code> file:
<pre lang="json">{
"$schema": "../../node_modules/bga-ts-template/schema/gameoptions.schema.json",

"100": {
"name": "Variant",
"values": {
// This is the current rule set we have implemented
"1": {
"name": "Standard",
"description": "Flip all outflanked discs."
},
"2": {
"name": "Reversi Bombs",
"description": "Flip all 8 adjacent discs."
}
}
}
}</pre>
<blockquote>See [https://en.doc.boardgamearena.com/Options_and_preferences:_gameoptions.json,_gamepreferences.json gameoptions.json] for more information about the options file for BGA games.</blockquote></li>
<li>Modify the <code>getTurnedOverDiscs</code> function in your <code>yourgamename.game.php</code> file to handle the new game option:
<pre lang="php">function getTurnedOverDiscs( $x, $y, $player, $board )
{
//...

foreach( $directions as $direction )
{
// If game option '100' is set to 2 (reversi bombs)
if ($this->gamestate->table_globals[100] == 2)
{
$current_x = $x + $direction[0];
$current_y = $y + $direction[1];
if( $current_x<1 || $current_x>8 || $current_y<1 || $current_y>8 )
continue; // Out of the board => stop here for this direction

if ($board[ $current_x ][ $current_y ] !== null)
// push the disc to be turned over
$turnedOverDiscs[] = array( 'x' => $current_x, 'y' => $current_y );

continue; // Don't do standard game logic
}
// Standard...
}

//...
}</pre></li>
<li>Fix the <code>playDisc</code> function to flip all turned disc instead of setting them to the active player:
<pre lang="php">// Let's place a disc at x,y and return all "$returned" discs to the active player
$other_id = self::getUniqueValueFromDb( "SELECT player_id FROM player WHERE player_id!='$player_id'" );
$sql = "UPDATE board SET board_player = CASE WHEN board_player = '$player_id' THEN '$other_id' ELSE '$player_id' END WHERE (board_x, board_y) IN (";
foreach( $turnedOverDiscs as $turnedOver )
//...</pre></li>
<li>Reload the game options from within the game manager page. See [https://github.com/NevinAF/bga-ts-template/blob/main/docs/tutorials/index.md#step-3---game-information--metadata Step 3.3] for more information.

https://github.com/NevinAF/bga-ts-template/tree/main/docs/tutorials/img/reversi/game_configuration.png
</li></ol>


https://github.com/NevinAF/bga-ts-template/tree/main/docs/tutorials/img/reversi/step12-4.gif


== User Preferences ==

User preferences is something cosmetic about the game interface which you want users to be able to controll. Reversi has a classic athstetic, but in this example, we will add a user preference to change the color of the board. This is not a great use case for user preferences, but it is a simple example.

<ol style="list-style-type: decimal;">
<li>Replace the contents of <code>shared/gamepreferences.jsonc</code> with the following:
<pre lang="json">{
"$schema": "../../node_modules/bga-ts-template/schema/gamepreferences.schema.json",
"101": {
"name": "Game Style",
"needReload": true,
"values": {
"1": {
"name": "Classic",
"cssPref": "game_style_classic"
},
"2": {
"name": "Wooden",
// Then this is added to the page, we will override the image urls in the css.
"cssPref": "game_style_wooden"
}
},
"default": 1
}
}</pre>
<blockquote>See [https://en.doc.boardgamearena.com/Options_and_preferences:_gameoptions.json,_gamepreferences.json gamepreferences.json] for more information about the options file for BGA games.</blockquote></li>
<li>Download the following images and add them to your <code>img</code> folder. They should be named ‘wooden_board.jpg’ and ‘wooden_tokens.png’.
<table align="center" width="50%">
<tr>
<td>
https://github.com/NevinAF/bga-ts-template/tree/main/docs/tutorials/img/reversi/assets/wooden_board.jpg
</td>
<td>
https://github.com/NevinAF/bga-ts-template/tree/main/docs/tutorials/img/reversi/assets/wooden_tokens.png
</td>
</tr>
</table></li>
<li>Add the following to your <code>yourgamename.scss</code> file to change the board and token images:
<pre lang="scss">// This overrides the #board + .token- images when the .game_style_wooden is automatically added to the page (by the user preference).
.game_style_wooden {
#board {
background-image: url('img/wooden_board.jpg');
}
.token-white, .token-black {
background-image: url('img/wooden_tokens.png');
}
}</pre></li>
<li>Refresh the game options in the game manager page. See [https://github.com/NevinAF/bga-ts-template/blob/main/docs/tutorials/index.md#step-3---game-information--metadata Step 3.3] for more information.

https://github.com/NevinAF/bga-ts-template/tree/main/docs/tutorials/img/reversi/game_configuration.png
</li>
<li>Reload the game and change the user preference to see the new board and token images:

https://github.com/NevinAF/bga-ts-template/tree/main/docs/tutorials/img/reversi/step13-5.gif
</li></ol>

Tutorial reversi

2025-03-03T13:47:47Z

Sean-the-sheep: Remove reference to dojo method because the tutorial now uses `document.querySelectorAll` instead.

If you want to use TypeScript, you can '''check out an updated version''' of the [[BGA Type Safe Template: Reversi|Reversi Tutorial]] which uses the [[BGA Type Safe Template]]. '''Important note: BGA Type Safe Template is a project created by a developer that is not part of the BGA team. This is currently not officially supported by BGA.''' {{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 26.
** Add <code>1,</code> to the players array (so you can start 1-player games while testing) - that's around line 29.
* Upload the <code>gameinfos.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.js</code> to add the <code>div</code> for your board at the beginning of the setup function.

Note: If you are building this game by following the tutorial, you will have a different project name than <code>reversi</code> (i.e. <code>mygame.js</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>
this.getGameAreaElement().insertAdjacentHTML('beforeend', `
<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 .js file ====
At first, we introduce a new 'div' element as a child of "board" to host all these tokens (in the template we started at the beginning of the setup function of the JS file):

<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: async function( x, y, player )
{
const 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 );

const anim = this.slideToObject( `disc_${x}${y}`, 'square_'+x+'_'+y );
await this.bgaPlayDojoAnimation(anim);
}
</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>bgaPlayDojoAnimation()</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 modules/php/Game.php file ====
Before we can show a token, we need to set the player colors in the <code>setupNewGame</code> function in <code>modules/php/Game.php</code>:

Replace <code>$default_colors = $gameinfos['player_colors'];</code> with the following line:
<pre>
$default_colors = 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>Game.php</code> is called during initial setup. This initializes our data and places the starting tokens on the board. At the beginning of the game, there should be 4 tokens on the board.

=== Initialize the Board in modules/php/Game.php file ===
Under <code>// TODO: setup the initial game situation here</code>, initialize the board<pre>
// 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>modules/php/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>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>modules/php/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>

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>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 [[Main game logic: Game.php|https://en.doc.boardgamearena.com/Main_game_logic:_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->notify->all( "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->notify->all( "turnOverDiscs", '', array(
'player_id' => $player_id,
'turnedOver' => $turnedOverDiscs
) );

$newScores = $this->getCollectionFromDb( "SELECT player_id, player_score FROM player", true );
$this->notify->all( "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>modules/php/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 tell BGA to listen to notifications we will add later (<code>playDisc</code> and <code>turnOverDiscs</code>) using promise-based notifications:

<pre>
setupNotifications: function()
{
console.log( 'notifications subscriptions setup' );

// automatically listen to the notifications, based on the `notif_xxx` function on this class.
this.bgaSetupPromiseNotifications();
}
</pre>

We will associate each of our 3 notifications with a method prefixed with <code>notif_</code>.

Let's have a look now on the <code>playDisc</code> notification handler method:<pre>
notif_playDisc: async function( args )
{
// Remove current possible moves (makes the board more clear)
document.querySelectorAll('.possibleMove').forEach(div => div.classList.remove('possibleMove'));

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

No surprise here, we re-used some existing stuff to:
* Remove the highlighted squares.
* Add a new disc on board, coming from player panel. That's where the async await part of <code>addDiscOnBoard</code> becomes useful.

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

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

// wait for the animations of all turned discs to be over before considering the notif done
await Promise.all(
args.turnedOver.map(disc =>
this.animateTurnOverDisc(disc, targetColor)
)
);
},

animateTurnOverDisc: async function(disc, targetColor) {
const discDiv = document.getElementById(`disc_${disc.x}${disc.y}`);
if (!this.bgaAnimationsActive()) {
// do not play animations if the animations aren't activated (fast replay mode)
discDiv.dataset.color = targetColor;
return Promise.resolve();
}

// Make the disc blink 2 times
const anim = dojo.fx.chain( [
dojo.fadeOut( { node: discDiv } ),
dojo.fadeIn( { node: discDiv } ),
dojo.fadeOut( {
node: discDiv,
onEnd: () => discDiv.dataset.color = targetColor,
} ),
dojo.fadeIn( { node: discDiv } )
] ); // end of dojo.fx.chain

await this.bgaPlayDojoAnimation(anim);
},
</pre>

The list of the discs to be turned over has been made available by our server side code in <code>args.turnedOver</code> (see previous paragraph). We loop through all these discs, and trigger a single disc animation using <code>animateTurnOverDisc</code>. This function creates a complex animation using <code>dojo.Animation</code> for the disc in parameter. 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>bgaPlayDojoAnimation()</code>.

And Also the notification to update the scores:

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

[[Category:Studio]]