This is a documentation for Board Game Arena: play board games online !

Tutorial reversi: Difference between revisions

From Board Game Arena
Jump to navigation Jump to search
(support warning)
 
(141 intermediate revisions by 32 users not shown)
Line 1: Line 1:
{{Studio_Framework_Navigation}}
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 ==
== Introduction ==
Line 9: Line 9:
* Know the [http://en.wikipedia.org/wiki/Reversi#Rules rules of Reversi].
* Know the [http://en.wikipedia.org/wiki/Reversi#Rules rules of Reversi].
* Know the languages used on BGA: PHP, SQL, HTML, CSS, Javascript
* 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]
* '''Setup your development environment''' [http://en.doc.boardgamearena.com/First_steps_with_BGA_Studio First Steps with BGA Studio]


== Create your first game ==
== Create your first game ==


With the initial skeleton of code provided initially, you can already start a game from the BGA Studio. For now, we are going to work with 1 player only. 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.
''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.
Thus, you can start a "Reversi" game, and arrive on a void, empty game. Yeah.


== Let it look like Reversi ==
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 ==


It's always a good idea to start with a little bit of graphic work. Why? Because this helps to figure out how the final game will be, and issues that may appear later.
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).
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 choose this one which fit perfectly (536x528):
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]]
[[File:Board.jpg]]


Note that we are using a jpg file. Jpg are lighter than png, so faster to load. Later we are going to use PNGs for discs for transparency purpose.
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.


Now, let's make it appears on our game:
* upload board.jpg in your "img/" directory.
* edit "reversi_reversi.tpl" to add a 'div' for your board:


<pre>
<pre>
<div id="board">
document.getElementById('game_play_area').insertAdjacentHTML('beforeend', `
</div>
  <div id="board">
  </div>
`);
</pre>
</pre>


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


  #board {
  #board {
Line 46: Line 89:
  }
  }


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


[[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!


== Make the squares appears ==
==== 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.


Now, what we need is to create some invisible HTML elements where squares are. These elements will be used as position references for white and black discs.  
===== Build the grid of squares =====
Obviously, we need 64 squares. To avoid writing 64 'div' elements on our template, we are going to use the "block" feature.
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>.


Let's modify our template like this:
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>
<pre>
<div id="board">
const board = document.getElementById('board');
    <!-- BEGIN square -->
const hor_scale = 64.8;
        <div id="square_{X}_{Y}" class="square" style="left: {LEFT}px; top: {TOP}px;"></div>
const ver_scale = 64.4;
    <!-- END square -->
for (let x=1; x<=8; x++) {
</div>
    for (let y=1; y<=8; y++) {
</pre>
        const left = Math.round((x - 1) * hor_scale + 10);
 
        const top = Math.round((y - 1) * ver_scale + 7);
As you can see, we created a "square" block, with 4 variable elements: X, Y, LEFT and TOP. Obviously, we are going to use this block 64 times during page load.
        // 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>`);
Let's do it in our "reversi.view.php" file:
    }
 
}
<pre>
        $this->page->begin_block( "reversi_reversi", "square" );
       
        $hor_scale = 64.8;
        $ver_scale = 64.4;
        for( $x=1; $x<=8; $x++ )
        {
            for( $y=1; $y<=8; $y++ )
            {
                $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>
</pre>


Note: as you can see, squares in our "board.jpg" files does not have an exact width/height in pixel, and that's the reason we are using floating point numbers here.
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:
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:


Line 109: Line 137:


Explanations:
Explanations:
* With "position: relative" on board, we ensure square elements are positioned relatively to board.
* With "<code>position: relative</code>" on board, we ensure square elements are positioned relatively to board.
* For the test, we use a red background color for the square. This is a useful tip to figure out if everything is fine with invisible elements.
* <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 our (beautiful) squares:
Let's refresh and check our (beautiful) squares:


[[File:reversi2.jpg]]
[[File:reversi2.jpg]]


== The discs ==
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.


Now, our board is ready to receive some disc tokens!
===== 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.]
[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.]


At first, we introduce a new 'div' element as a child of "board" to host all these tokens (in our template):
=== 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>
<pre>
    <!-- END square -->
<div id="board">
      
      
     <div id="tokens">
     <div id="discs">
     </div>
     </div>
</div>
</div>
</pre>
</pre>


Then, let's introduce a new piece of art with the discs. We need some transparency here so we are using a png file:
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]]
[[File:tokens.png]]


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


Important: we are using ONE file for both discs. It's really important that you use a minimum number of graphic files for your game with this "CSS sprite" technique, because it makes the game loading faster and more reliable. [http://www.w3schools.com/css/css_image_sprites.asp Read more about CSS sprites].
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].
 
Now, let's separate the disc with some CSS stuff:


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


With this CSS code, we apply the classes "token" and "tokencolor_ffffff" to a div element and we've got a white token. Yeah.
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 "position: absolute" which allows us to position tokens on the board and make them "slide" to their positions.
Note the "<code>position: absolute</code>" which allows us to position tokens on the board and make them "slide" to their positions.


Now, let's make a first token appear on our board. Disc 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, with a BGA Framework technique called "JS template".
==== 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


In our template file (reversi_reversi.tpl), let's create the piece of HTML needed to display our token:
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>
<pre>
<script type="text/javascript">
addDiscOnBoard: function( x, y, player )
 
{
// Templates
    var color = this.gamedatas.players[ player ].color;
 
   
var jstpl_token='<div class="token tokencolor_${color}" id="token_${x_y}"></div>';
    document.getElementById('discs').insertAdjacentHTML('beforeend', `<div class="disc" data-color="${color}" id="disc_${x}${y}"></div>`);
 
   
</script>
    this.placeOnObject( `disc_${x}${y}`, 'overall_player_board_'+player );
</pre>
    this.slideToObject( `disc_${x}${y}`, 'square_'+x+'_'+y ).play();
 
},
Note: we already created the "templates" section for you in the game skeleton.
 
As you can see, we defined a JS template named "jstpl_token" with a piece of HTML and two variables: the color of the token and its x/y coordinates. Note that the syntax of the argument is different for template block variables (brackets) and JS template variables (dollar and brackets).
 
Now, let's create a method in our Javascript code (in the "reversi.js" file) that will make a token appear on the board, using this template:
 
<pre>
        addTokenOnBoard: function( x, y, player )
        {
            dojo.place( this.format_block( 'jstpl_token', {
                x_y: x+'_'+y,
                color: this.gamedatas.players[ player ].color
            } ) , 'tokens' );
           
            this.placeOnObject( 'token_'+x+'_'+y, 'overall_player_board_'+player );
            this.slideToObject( 'token_'+x+'_'+y, 'square_'+x+'_'+y ).play();
        },
</pre>
</pre>


At first, with "dojo.place" and "this.format_block" methods, we create a HTML piece of code and insert it as a new child of "tokens" div element.
===== 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.


Then, with BGA "this.placeOnObject" method, we place this element over the panel of some player. Immediately after, using BGA "this.slideToObject" method, we make the disc slide to the "square" element, its final destination.
Note: don't forget to call the <code>play()</code>, otherwise the token will remain at its original location.


Note: don't forget to call the "play()", otherwise the token remains 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.


Note: note that during all the process, the parent of the new disc HTML element will remain "tokens". placeOnObject and slideToObject 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>:


Before we can show a token, we need to set the player colors in the setupNewGame function in reversi.game.php:
Replace <code>$default_colors = $gameinfos['player_colors'];</code> with the following line:
<pre>
<pre>
        $default_colors = array( "ffffff", "000000" );
$default_colors = array( "ffffff", "000000" );
</pre>
</pre>


Note: Probably you'll have to remove the line "self::reattributeColorsBasedOnPreferences( $players, $gameinfos['player_colors'] );".
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


Now, to test if everything works fine, just add "this.addTokenOnBoard( 2, 2, [player_id] )" in the "setup" Javascript method in reversi.js, and reload the page.
==== <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:
A token should appear and slide immediately to its position, like this:
Line 215: Line 248:
== The database ==
== The database ==


We did most of the client-side programming, so let's have a look on the other side now.
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.


To design the database model of our game, the best thing to do is to follow the "Go to game database" link at the bottom of our game, to access the database directly with a [http://www.phpmyadmin.net/ PhpMyAdmin] instance.
=== 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.


Then, you can create the tables you need for your table (do not remove existing tables!), and report every SQL command used in your "dbmodel.sql" file.
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.


[[File:reversi4.jpg]]
'''Note''': do not remove existing tables


The database model of Reversi is very simple: just one table with the squares of the board. In our dbmodel.sql, we have this:
=== 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>
<pre>
Line 231: Line 268:
   `board_player` int(10) unsigned DEFAULT NULL,
   `board_player` int(10) unsigned DEFAULT NULL,
   PRIMARY KEY (`board_x`,`board_y`)
   PRIMARY KEY (`board_x`,`board_y`)
) ENGINE=InnoDB;
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
</pre>
</pre>


Now, a new database with a "board" table will be created each time we start a Reversi game. This is why after modifying our dbmodel.sql it's a good time to stop & start again our game.
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 ==
== Setup the initial game position ==


The "setupNewGame" method of our reversi.game.php is called during initial setup: this is the place to initialize our data and to place the initial tokens on the board (initially, there are 4 tokens on the board).
'''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.


Let's do this:
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.


<pre>
=== Initialize the Board in modules/php/Game.php file ===
        // Init the board
Under <code>// TODO: setup the initial game situation here</code>, initialize the board<pre>
        $sql = "INSERT INTO board (board_x,board_y,board_player) VALUES ";
// Init the board
        $sql_values = array();
$sql = "INSERT INTO board (board_x,board_y,board_player) VALUES ";
        list( $blackplayer_id, $whiteplayer_id ) = array_keys( $players );
$sql_values = array();
        for( $x=1; $x<=8; $x++ )
list( $blackplayer_id, $whiteplayer_id ) = array_keys( $players );
        {
for( $x=1; $x<=8; $x++ )
            for( $y=1; $y<=8; $y++ )
{
            {
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 = "NULL";
                    $token_value = "'$whiteplayer_id'";
if( ($x==4 && $y==4) || ($x==5 && $y==5) )  // Initial positions of white player
                else if( ($x==4 && $y==5) || ($x==5 && $y==4) )  // Initial positions of black player
$token_value = "'$whiteplayer_id'";
                    $token_value = "'$blackplayer_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_values[] = "('$x','$y',$token_value)";
            }
}
        }
}
        $sql .= implode( $sql_values, ',' );
$sql .= implode( ',', $sql_values );
        self::DbQuery( $sql );
$this->DbQuery( $sql );
       
       
        // Active first player
        self::activeNextPlayer(); 
</pre>
</pre>


As you can see, we create one table entry for each square, with a "NULL" value which means "empty square". Of course, for 4 specific squares, we place an initial token.
==== 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.


At the end, we call activeNextPlayer to make the first player active at the beginning of the game.
=== 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>


Now, we need to make these tokens appear on the client side. To achieve this, the first step is to return the token positions with our "getAllDatas" PHP method (called during each page reload):
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>
<pre>
        // Get reversi board token
$sql = "SELECT player_id id, player_score score, player_color color FROM player ";
        $result['board'] = self::getObjectListFromDB( "SELECT board_x x, board_y y, board_player player
                                                      FROM board
                                                      WHERE board_player IS NOT NULL" );
</pre>
</pre>


As you can see, we are using the BGA framework "getObjectListFromDB" method that formats the result of this SQL query in a PHP array with x, y and player attributes.
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>.


The last thing we need to do is to process this array client side, and place a disc token on the board for each array item. Of course, we are doing this is our Javascript "setup" method:
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>
<pre>
            for( var i in gamedatas.board )
for( var i in gamedatas.board )
            {
{
                var square = gamedatas.board[i];
    var square = gamedatas.board[i];
               
   
                if( square.player !== null )
    if( square.player !== null )
                {
    {
                    this.addTokenOnBoard( square.x, square.y, square.player );
        this.addDiscOnBoard( square.x, square.y, square.player );
                }
    }
            }
}
</pre>
</pre>


As you can see, our "board" entry created in "getAllDatas" can be used here as "gamedatas.board" in our Javascript. We are using our previously developed "addTokenOnBoard" method.
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:
Reload... and here we are:


[[File:reversi5.jpg]]
[[File:reversi5.jpg]]


It starts to smell Reversi here...
It starts to feel like Reversi here...


== The game state machine ==
== The game state machine ==


Now, let's stop our game again, because we are going to start the core game logic.
Stop your game, again. You're about to start the core game logic.


You already read the "Focus on BGA game state machine", so you know that this is the heart of your game logic. For reversi, it's very simple. Here's a diagram of our game state machine:
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]]
[[File:reversi6.jpg]]


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


<pre>
<pre>
$machinestates = array(
$machinestates = array(


     1 => array(
     ST_BGA_GAME_SETUP => array(
         "name" => "gameSetup",
         "name" => "gameSetup",
         "description" => clienttranslate("Game setup"),
         "description" => clienttranslate("Game setup"),
         "type" => "manager",
         "type" => "manager",
         "action" => "stGameSetup",
         "action" => "stGameSetup",
         "transitions" => array( "" => 10 )
         "transitions" => array( "" => ST_PLAYER_PLAY_DISC )
     ),
     ),
      
      
     10 => array(
     ST_PLAYER_PLAY_DISC => array(
         "name" => "playerTurn",
         "name" => "playerTurn",
"description" => clienttranslate('${actplayer} must play a disc'),
"description" => clienttranslate('${actplayer} must play a disc'),
Line 332: Line 389:
         "type" => "activeplayer",
         "type" => "activeplayer",
         "args" => "argPlayerTurn",
         "args" => "argPlayerTurn",
         "possibleactions" => array( 'playDisc' ),
         "possibleactions" => array( 'actPlayDisc' ),
         "transitions" => array( "playDisc" => 11, "zombiePass" => 11 )
         "transitions" => array( "playDisc" => ST_NEXT_PLAYER, "zombiePass" => ST_NEXT_PLAYER )
     ),
     ),
      
      
     11 => array(
     ST_NEXT_PLAYER => array(
         "name" => "nextPlayer",
         "name" => "nextPlayer",
         "type" => "game",
         "type" => "game",
         "action" => "stNextPlayer",
         "action" => "stNextPlayer",
         "updateGameProgression" => true,         
         "updateGameProgression" => true,         
         "transitions" => array( "nextTurn" => 10, "cantPlay" => 11, "endGame" => 99 )
         "transitions" => array( "nextTurn" => ST_PLAYER_PLAY_DISC, "cantPlay" => ST_NEXT_PLAYER, "endGame" => ST_END_GAME )
     ),
     ),
    
    
     99 => array(
     ST_END_GAME => array(
         "name" => "gameEnd",
         "name" => "gameEnd",
         "description" => clienttranslate("End of game"),
         "description" => clienttranslate("End of game"),
Line 355: Line 412:
</pre>
</pre>


Now, let's create in reversi.game.php the methods that are declared in this game states description file:
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.
* argPlayerTurn
 
* stNextPlayer
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.
... 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 "playerTurn" right after the initial setup. That's why the status bar contains the description of playerTurn state ("XXXX must play a disc"):
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]]
[[File:reversi7.jpg]]
Line 367: Line 446:
== The rules ==
== The rules ==


Now, what we would like to do is to indicate to the current player where she is allowed to play. The idea is to build a "getPossibleMoves" PHP method that return a list of coordinates where she is allowed to play. This method will be used in particular:
We will use the <code>getPossibleMoves</code> PHP method to:
* As we just said, to help the player to see where she can play.
* Indicate to the current player where she is allowed to play by returning a list of coordinates
* When the player plays, to check if she has the right to play here.
* 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:
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 "getTurnedOverDiscs(x,y)" method that return coordinates of discs that would be turned over if a token would be played at x,y.
* 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, call the "getTurnedOverDiscs" method on each of them. If at least 1 token is turned over, this is a valid move.
* 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.


One important thing to keep in mind is the following: making a database query is slow, so please don't load the entire game board with a SQL query multiple time. In our implementation, we load the entire board once at the beginning of "getPossibleMoves", and then pass the board as an argument to all methods.
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 reversi.game.php.
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 ==
== Display allowed moves ==


Now, what we want to do is highlight the squares where the player can place a disc.
Now we want to highlight the squares where the player can place a disc.


To do this, we are using the "argPlayerTurn" method. This method is called each time we enter into "playerTurn" game state, and its result is transfered automatically to the client-side:
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>
<pre>
 
function argPlayerTurn(): array
    function argPlayerTurn()
{
    {
    return [
        return array(
        'possibleMoves' => $this->getPossibleMoves( intval($this->getActivePlayerId()) )
            'possibleMoves' => self::getPossibleMoves( self::getActivePlayerId() )
    ];
        );
}
    }
</pre>
</pre>


We are of course using the "getPossibleMoves" method we just developed.
We use the <code>getPossibleMoves</code> method we just developed.


Now, let's go to the client side to use the data returned by the method above. We are using the "onEnteringState" Javascript method that is called each time we enter into a new game state:
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>
<pre>
Line 413: Line 495:
</pre>
</pre>


So, when we are entering into "playerTurn" game state, we are calling our "updatePossibleMoves" method. This method looks like this:
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>
<pre>
        updatePossibleMoves: function( possibleMoves )
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 ] )
         {
         {
             // Remove current possible moves
             // x,y is a possible move
             dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );
             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.


            for( var x in possibleMoves )
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.
            {
 
                for( var y in possibleMoves[ x ] )
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.
                {
                    // x,y is a possible move
                    dojo.addClass( 'square_'+x+'_'+y, 'possibleMove' );
                }           
            }
                       
            this.addTooltipToClass( 'possibleMove', '', _('Place a disc here') );
        },
</pre>


The idea here is that we've created a CSS class ("possibleMove") that can be applied to a "square" element to highlight it:
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>
<pre>
.possibleMove {
.possibleMove {
     background-color: white;
     background-color: white;
     opacity: 0.2;
     opacity: 0.2;  
    filter:alpha(opacity=20); /* For IE8 and earlier */ 
     cursor: pointer;   
     cursor: pointer;   
}
}
</pre>
</pre>


At first, we remove all "possibleMove" classes currently applied with the very useful combination of "dojo.query" and "removeClass" method.


Then we loop through all possible moves our PHP "updatePossibleMoves" function created for us, and add the "possibleMove" class to each corresponding square.
Finally, we use the BGA framework "addTooltipToClass" method to associate a tooltip to all those highlighted squares so that players can understand their meaning.


And here we are:
And here we are:
Line 457: Line 539:


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:
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 "possibleMoves" square, send the move to the server.
* 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.
* Server side, check the move is correct, apply Reversi rules and jump to next player.
* Client side, change the disc position to reflect the move.
* Client side, change the token position to reflect the move.


Thus, what we do first is associate each click on a square to one of our method. We are doing this in our Javascript "setup" method:
First we associate each click on a square to one of our methods using our Javascript <code>setup</code> method:


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


Line 472: Line 554:


<pre>
<pre>
        onPlayDisc: function( evt )
onPlayDisc: function( evt )
        {
{
            // Stop this event propagation
    // Stop this event propagation
            dojo.stopEvent( evt );
    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];


            // Get the cliqued square x and y
    if(!document.getElementById(`square_${x}_${y}`).classList.contains('possibleMove')) {
            // Note: square id format is "square_X_Y"
        // This is not a possible move => the click does nothing
            var coords = evt.currentTarget.id.split('_');
        return ;
            var x = coords[1];
    }
            var y = coords[2];


            if( ! dojo.hasClass( 'square_'+x+'_'+y, 'possibleMoves' ) )
    this.bgaPerformAction("actPlayDisc", {
            {
        x:x,
                // This is not a possible move => the click does nothing
        y:y
                return ;
    });
            }
},
           
            if( this.checkAction( 'playDisc' ) )    // Check that this action is possible at this moment
            {           
                this.ajaxcall( "/reversi/reversi/playDisc.html", {
                    x:x,
                    y:y
                }, this, function( result ) {} );
            }           
        },
</pre>
</pre>


What we do here is:
What we do here is:
* We stop the propagation of the Javascript "onclick" event. Otherwise, it can lead to random behavior so it's always a good idea.
* 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 "evt.currentTarget.id".
* We get the x/y coordinates of the square by using <code>evt.currentTarget.id</code>
* We check that clicked square has the "possibleMoves" class, otherwise we know for sure that we can't play there.
* We check that clicked square has the <code>possibleMove</code> class, otherwise we know for sure that we can't play there.
* We check that "playDisc" action is possible, according to current game state (see "possibleactions" entry in our "playerTurn" game state defined above). This check is important to avoid issues if a player double clicks on a square.
* 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.
* Finally, we make a call to the server using BGA "ajaxcall" method with argument x and y.
 
Now, we have to manage this "playDisc" action on the server side. At first, we introduce a "playDisc" entry point in our "reversi.action.php":
 
<pre>
    public function playDisc()
    {
        self::setAjaxMode();   
        $x = self::getArg( "x", AT_posint, true );
        $y = self::getArg( "y", AT_posint, true );
        $result = $this->game->playDisc( $x, $y );
        self::ajaxResponse( );
    }
</pre>


As you can see, we get the 2 arguments x and y from the javascript call, and call a corresponding "playDisc" method in our game logic.
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>):
 
Now, let's have a look of this playDisc method:


<pre>
<pre>
    function playDisc( $x, $y )
function actPlayDisc( int $x, int $y )
    {
{
        // Check that this player is active and that this action is possible at this moment
        self::checkAction( 'playDisc' ); 
</pre>
</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]] )
... at first, we check that this action is possible according to current game state (see "possible action"). We already did it on client side, but it's important to do it on server side too (otherwise it would be possible to cheat).
 
<pre>
<pre>
        $player_id = intval($this->getActivePlayerId());
       
         // Now, check if this is a possible move
         // Now, check if this is a possible move
         $board = self::getBoard();
         $board = $this->getBoard();
         $player_id = self::getActivePlayerId();
         $turnedOverDiscs = $this->getTurnedOverDiscs( $x, $y, $player_id, $board );
        $turnedOverDiscs = self::getTurnedOverDiscs( $x, $y, $player_id, $board );
          
          
         if( count( $turnedOverDiscs ) > 0 )
         if( count( $turnedOverDiscs ) > 0 )
Line 543: Line 603:
</pre>
</pre>


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


<pre>
<pre>
Line 557: Line 617:
             $sql .= "('$x','$y') ) ";
             $sql .= "('$x','$y') ) ";
                        
                        
             self::DbQuery( $sql );
             $this->DbQuery( $sql );
 
</pre>
</pre>


Line 569: Line 628:
                     SELECT COUNT( board_x ) FROM board WHERE board_player=player_id
                     SELECT COUNT( board_x ) FROM board WHERE board_player=player_id
                     )";
                     )";
             self::DbQuery( $sql );
             $this->DbQuery( $sql );
              
              
             // Statistics
             // Statistics
             self::incStat( count( $turnedOverDiscs ), "turnedOver", $player_id );
             $this->incStat( count( $turnedOverDiscs ), "turnedOver", $player_id );
             if( ($x==1 && $y==1) || ($x==8 && $y==1) || ($x==1 && $y==8) || ($x==8 && $y==8) )
             if( ($x==1 && $y==1) || ($x==8 && $y==1) || ($x==1 && $y==8) || ($x==8 && $y==8) )
                 self::incStat( 1, 'discPlayedOnCorner', $player_id );
                 $this->incStat( 1, 'discPlayedOnCorner', $player_id );
             else if( $x==1 || $x==8 || $y==1 || $y==8 )
             else if( $x==1 || $x==8 || $y==1 || $y==8 )
                 self::incStat( 1, 'discPlayedOnBorder', $player_id );
                 $this->incStat( 1, 'discPlayedOnBorder', $player_id );
             else if( $x>=3 && $x<=6 && $y>=3 && $y<=6 )
             else if( $x>=3 && $x<=6 && $y>=3 && $y<=6 )
                 self::incStat( 1, 'discPlayedOnCenter', $player_id );
                 $this->incStat( 1, 'discPlayedOnCenter', $player_id );
 
</pre>
</pre>


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


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


... then we notify about all these changes. We are using for that 3 notifications ('playDisc', 'turnOverDiscs' and 'newScores' that we are going to implement on client side later). Note that the description of the 'playDisc' notification will be logged in the game log.
... 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>
<pre>
Line 612: Line 670:
         }
         }
         else
         else
             throw new feException( "Impossible move" );
             throw new \BgaSystemException( "Impossible move" );
     }
     }
</pre>
</pre>


... finally, we jump to the next game state if everything goes fine ('playDisc' is also the name of a transition in the 'playerTurn' game state description above).
... 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 stats.inc.php:
 
To make the statistics work, we have to initialize them in <code>stats.json</code>:


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


A last thing to do on the server side is to activate the next player when we enter the "nextPlayer" game state:
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>
<pre>
     function stNextPlayer()
     function stNextPlayer(): void
     {
     {
         // Activate next player
         // Active next player
         $player_id = self::activeNextPlayer();
         $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 ;
        }
          
          
         self::giveExtraTime( $player_id );
         // Can this player play?
         $this->gamestate->nextState( 'nextTurn' );
 
        $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>
</pre>


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


[[File:reversi9.jpg]]
[[File:reversi9.jpg]]
Line 665: Line 771:
Now, what we have to do is process the notifications sent by the server and make the move appear on the interface.
Now, what we have to do is process the notifications sent by the server and make the move appear on the interface.


In our "setupNotifications" method, we register 2 methods for the 2 notifications we created at the previous step ('playDisc' and 'turnOverDiscs'):
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>
<pre>
             dojo.subscribe( 'playDisc', this, "notif_playDisc" );
             const notifs = [
            this.notifqueue.setSynchronous( 'playDisc', 500 );
                ['playDisc', 500],
            dojo.subscribe( 'turnOverDiscs', this, "notif_turnOverDiscs" );
                ['turnOverDiscs', 1500],
             this.notifqueue.setSynchronous( 'turnOverDiscs', 1500 );
                ['newScores', 1],
            dojo.subscribe( 'newScores', this, "notif_newScores" );
            ];
            this.notifqueue.setSynchronous( 'newScores', 500 );
   
             notifs.forEach((notif) => {
                dojo.subscribe(notif[0], this, `notif_${notif[0]}`);
                this.notifqueue.setSynchronous(notif[0], notif[1]);
            });
</pre>
</pre>


As you can see, we associate our 2 notifications with 2 methods with the "notif_" prefix. At the same time, we define these notifications as "synchronous", with a duration in millisecond (500 for the first one, and 1500 for the second one). 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:
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
* Make a disc slide from the player panel to its place on the board
* (wait 500ms)
* (wait 500ms)
* Make all turned over discs blink (and of course turned them over)
* Make all turned over discs blink (and of course turned them over)
* (wait 1500ms)
* (wait 1500ms)
* Let the next player play.
* 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 "playDisc" notification handler method:
Let's have a look now on the <code>playDisc</code> notification handler method:


<pre>
<pre>
        notif_playDisc: function( notif )
notif_playDisc: function( notif )
        {
{
            // Remove current possible moves (makes the board more clear)
    // Remove current possible moves (makes the board more clear)
            dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );      
    document.querySelectorAll('.possibleMove').forEach(div => div.classList.remove('possibleMove'));
       
 
            this.addTokenOnBoard( notif.args.x, notif.args.y, notif.args.player_id );
    this.addDiscOnBoard( notif.args.x, notif.args.y, notif.args.player_id );
        },
},
</pre>
</pre>


Line 699: Line 812:
* Add a new disc on board, coming from player panel.
* Add a new disc on board, coming from player panel.


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


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


            // Make these discs blink and set them to the specified color
    // Made these discs blinking and set them to the specified color
            for( var i in notif.args.turnedOver )
    for( var i in notif.args.turnedOver )
            {
    {
                var token = notif.args.turnedOver[ i ];
        var disc = notif.args.turnedOver[ i ];
               
       
                // Make the token blink 2 times
        // Make the disc blink 2 times
                var anim = dojo.fx.chain( [
        var anim = dojo.fx.chain( [
                    dojo.fadeOut( { node: 'token_'+token.x+'_'+token.y } ),
            dojo.fadeOut( { node: 'disc_'+disc.x+''+disc.y } ),
                    dojo.fadeIn( { node: 'token_'+token.x+'_'+token.y } ),
            dojo.fadeIn( { node: 'disc_'+disc.x+''+disc.y } ),
                    dojo.fadeOut( {  
            dojo.fadeOut( {  
                                    node: 'token_'+token.x+'_'+token.y,
                            node: 'disc_'+disc.x+''+disc.y,
                                    onEnd: function( node ) {
                            onEnd: node => $(node).dataset.color = targetColor,
                            } ),
            dojo.fadeIn( { node: 'disc_'+disc.x+''+disc.y  } )
                           
        ] ); // end of dojo.fx.chain


                                        // Remove any color class
        // ... and launch the animation
                                        dojo.removeClass( node, [ 'tokencolor_000000', 'tokencolor_ffffff' ] );
        anim.play();              
                                        // ... and add the good one
    }
                                        dojo.addClass( node, 'tokencolor_'+targetColor );
},
                                                           
</pre>
                                    }  
                                  } ),
                    dojo.fadeIn( { node: 'token_'+token.x+'_'+token.y  } )
                               
                ] ); // end of dojo.fx.chain


                // ... and launch the animation
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].
                anim.play();               
            }
        },
</pre>


The list of the discs to be turned over has been made available by our server side code in "notif.args.turnedOver" (see previous paragraph). We loop through all these discs, and create a complex animation using dojo.Animation 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:
And Also the notification to update the scores:
Line 753: Line 861:




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 "play()".
[[Category:Studio]]

Latest revision as of 11:14, 24 October 2024

If you want to use TypeScript, you can check out an updated version of the 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.

Game File Reference



Useful Components

Official

  • Deck: a PHP component to manage cards (deck, hands, picking cards, moving cards, shuffle deck, ...).
  • Draggable: a JS component to manage drag'n'drop actions.
  • Counter: a JS component to manage a counter that can increase/decrease (ex: player's score).
  • ExpandableSection: a JS component to manage a rectangular block of HTML than can be displayed/hidden.
  • Scrollmap: a JS component to manage a scrollable game area (useful when the game area can be infinite. Examples: Saboteur or Takenoko games).
  • Stock: a JS component to manage and display a set of game elements displayed at a position.
  • Zone: a JS component to manage a zone of the board where several game elements can come and leave, but should be well displayed together (See for example: token's places at Can't Stop).

Undocumented component (if somebody knows please help with docs)

  • Wrapper: a JS component to wrap a <div> element around its child, even if these elements are absolute positioned.

Unofficial



Game Development Process



Guides for Common Topics



Miscellaneous Resources

Introduction

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

Before you read this tutorial, you must:

Create your first game

Note: you should already have created a project following instructions in 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 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 gameinfos.inc.php file:
    • Change the bgg_id value from 0 to 2389 - that's around line 26.
    • Add 1, to the players array (so you can start 1-player games while testing) - that's around line 29.
  • Upload the gameinfos.inc.php file to the SFTP server (see 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 Ctrl+F5 or Shift+F5 or Ctrl+Shift+R

Mac

Chrome or Firefox: Press Shift+Command+R

Safari for Mac: Press Command+Option+E 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):

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 board.jpg in your img/ directory.
  • edit reversi.js to add the div 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 reversi (i.e. mygame.js). The file names in your project will be different than shown in this tutorial, replacing reversi with your project name. Be sure that any code (other than comments) that references reversi is changed to your actual project name.


document.getElementById('game_play_area').insertAdjacentHTML('beforeend', `
  <div id="board">
  </div>
`);
  • edit your reversi.css 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: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 div elements on our template, we are going to generate the squares on JS setup.

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

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>`);
    }
}

Note: as you can see, squares in our board.jpg 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:

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

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

Explanations:

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

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

Reversi2.jpg

Now that you know the squares are there, you can remove the test line background-color: red; from your .square 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):

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

Note: discs 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:

Tokens.png

Upload this image file tokens.png in your img/ 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. Read more about CSS sprites.

Style the Tokens in .css file

.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%; }

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 "position: absolute" 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 reversi.js file) that will make a token appear on the board, using this template. Add under the section //// Utility methods:

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();
},  
Utility Method Explanation
  • with element.insertAdjacentHTML method, we create a HTML piece of code and insert it as a new child of tokens div element.
  • with this.placeOnObject BGA method, we place this element over the panel of some player.
  • Immediately after, using this.slideToObject BGA method, we make the token slide to the square element, its final destination.
  • 'overall_player_board_'+player 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 play(), otherwise the token will remain at its original location.

Note: during this process, the parent of the new token HTML element will stay tokens. placeOnObject and slideToObject 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 setupNewGame function in modules/php/Game.php:

Replace $default_colors = $gameinfos['player_colors']; with the following line:

$default_colors = array( "ffffff", "000000" );

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

Test the Token

Now, to test if everything works fine

addTokenOnBoard() in .js file to Test

In reversi.js, in setup: function, 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:

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 dbmodel.sql file.

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

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;

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

Test the Table

Now, a new database with a board table will be created each time we start a Reversi game. This is why after modifying our dbmodel.sql 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 player_ids within the database. Otherwise, the game will crash.

The setupNewGame method of our Game.php 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 // TODO: setup the initial game situation here, initialize the board

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

Board Initialization Explanation

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

After this, we set activeNextPlayer 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 this->reattributeColorsBasedOnPreferences() in SetupNewGame(). 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 getAllDatas() PHP method. getAllDatas() is called during each page reload.

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

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

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

$sql = "SELECT player_id id, player_score score, player_color color FROM player ";

We are using the BGA framework's getObjectListFromDB() 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 board.

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 setup method under the code we added to generate the squares.

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

for( var i in gamedatas.board )
{
    var square = gamedatas.board[i];
    
    if( square.player !== null )
    {
        this.addDiscOnBoard( square.x, square.y, square.player );
    }
}

The board entry created in getAllDatas() is used here as gamedatas.board

Test the Game Start

Reload... and here we are:

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 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:

Reversi6.jpg

Build your States

And here's our states.inc.php, according to this diagram:

$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"
    )

);

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 modules/php/constants.inc.php :

<?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;

?>

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


Now, in modules/php/Game.php let's create the methods that are declared in this game states description file:

  • argPlayerTurn: referenced in the args property of the playerTurn 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 onEnteringState or to set arguments in the gamestate description.
  • stNextPlayer: referenced in the action property of the nextPlayer 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 playerTurn right after the initial setup. That's why the status bar contains the description of playerTurn state ("XXXX must play a disc"):

Reversi7.jpg

The rules

We will use the getPossibleMoves 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

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

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 getTurnedOverDiscs(x,y) method that returns coordinates of discs that would be turned over if a token would be played at x,y.
  • Loop through all free squares of the board and call the getTurnedOverDiscs 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 getPossibleMoves, 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 Game.php. 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 argPlayerTurn method in modules/php/Game.php. This method is called on the server each time we enter into playerTurn game state, and its result is transferred automatically to the client-side:

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

We use the getPossibleMoves method we just developed.

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

        onEnteringState: function( stateName, args )
        {
           console.log( 'Entering state: '+stateName );
            
            switch( stateName )
            {
            case 'playerTurn':
                this.updatePossibleMoves( args.args.possibleMoves );
                break;
            }
        },

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

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') );
},

Here's what this does. At first, it removes all possibleMove classes currently applied with the very useful document.querySelectorAll method.

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

Finally, it uses the BGA framework addTooltipToClass 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 (possibleMove) that can be applied to a square element to highlight it:

.possibleMove {
    background-color: white;
    opacity: 0.2; 
    cursor: pointer;  
}


And here we are:

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 possibleMove 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 setup method:

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

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:

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
    });
},

What we do here is:

  • We stop the propagation of the Javascript onclick 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 evt.currentTarget.id
  • We check that clicked square has the possibleMove class, otherwise we know for sure that we can't play there.
  • Finally, we make a call to the server using BGA bgaPerformAction method with argument x and y. This call will check that actPlayDisc action is possible, according to current game state (see possibleactions entry in our playerTurn 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 actPlayDisc action on the server side. Add a corresponding actPlayDisc method in our game logic (Game.php):

function actPlayDisc( int $x, int $y )
{

(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:_Game.php#Actions_%28autowired%29 )

        $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!

...now, we are using the getTurnedOverDiscs method again to check that 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') ) ";
                       
            $this->DbQuery( $sql );

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

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

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

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

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

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

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

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

{
  "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"
    }
  }
}

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

    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' );
        }
    }

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

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 setupNotifications method in reversi.js, we register 2 methods for the 2 notifications we created at the previous step (playDisc and turnOverDiscs):

            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]);
            });

We will associate each of our 3 notifications with a method prefixed with notif_. 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 notif_<notifName> functions we are about to create.

Let's have a look now on the playDisc notification handler method:

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 );
},

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 turnOverDiscs notification:

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();                
    }
},

The list of the discs to be turned over has been made available by our server side code in notif.args.turnedOver (see previous paragraph). We loop through all these discs, and create a complex animation using dojo.Animation for each of them. The complete documentation on dojo animations 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 play().

And Also the notification to update the scores:

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 );
            }
        },