http://en.doc.boardgamearena.com/api.php?action=feedcontributions&user=Christopheryoder&feedformat=atomBoard Game Arena - User contributions [en]2024-03-28T17:59:33ZUser contributionsMediaWiki 1.39.0http://en.doc.boardgamearena.com/index.php?title=Tutorial_reversi&diff=1369Tutorial reversi2015-02-05T19:36:23Z<p>Christopheryoder: /* Let's play */</p>
<hr />
<div><br />
== Introduction ==<br />
<br />
Using this tutorial, you can build a complete working game on the BGA environment: Reversi.<br />
<br />
Before you read this tutorial, you must:<br />
* Read the overall presentations of the BGA Framework ([[Studio|see here]]).<br />
* Know the [http://en.wikipedia.org/wiki/Reversi#Rules rules of Reversi].<br />
* Know the languages used on BGA: PHP, SQL, HTML, CSS, Javascript.<br />
<br />
== Create your first game ==<br />
<br />
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 this 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.<br />
<br />
Thus, you can start a "Reversi" game, and arrive on a void, empty game. Yeah.<br />
<br />
== Let it look like Reversi ==<br />
<br />
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.<br />
<br />
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).<br />
<br />
For Reversi, it's useless to have a 750x750px board - much too big, so we choose this one which fit perfectly (536x528):<br />
<br />
[[File:Board.jpg]]<br />
<br />
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.<br />
<br />
Now, let's make it appears on our game:<br />
* upload board.jpg in your "img/" directory.<br />
* edit "reversi_reversi.tpl" to add a 'div' for your board:<br />
<br />
<pre><br />
<div id="board"><br />
</div><br />
</pre><br />
<br />
* edit your reversi.css file to transform it into a visible board:<br />
<br />
#board {<br />
width: 536px;<br />
height: 528px;<br />
background-image: url('img/board.jpg');<br />
}<br />
<br />
Refresh your page. Here's your board:<br />
<br />
[[File:reversi1.jpg]]<br />
<br />
== Make the squares appears ==<br />
<br />
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. <br />
Obviously, we need 64 squares. To avoid writing 64 'div' elements on our template, we are going to use the "block" feature.<br />
<br />
Let's modify our template like this:<br />
<br />
<pre><br />
<div id="board"><br />
<!-- BEGIN square --><br />
<div id="square_{X}_{Y}" class="square" style="left: {LEFT}px; top: {TOP}px;"></div><br />
<!-- END square --><br />
</div><br />
</pre><br />
<br />
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.<br />
<br />
Let's do it in our "reversi.view.php" file:<br />
<br />
<pre><br />
$this->page->begin_block( "reversi_reversi", "square" );<br />
<br />
$hor_scale = 64.8;<br />
$ver_scale = 64.4;<br />
for( $x=1; $x<=8; $x++ )<br />
{<br />
for( $y=1; $y<=8; $y++ )<br />
{<br />
$this->page->insert_block( "square", array(<br />
'X' => $x,<br />
'Y' => $y,<br />
'LEFT' => round( ($x-1)*$hor_scale+10 ),<br />
'TOP' => round( ($y-1)*$ver_scale+7 )<br />
) );<br />
} <br />
}<br />
</pre><br />
<br />
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.<br />
<br />
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:<br />
<br />
<pre><br />
#board {<br />
width: 536px;<br />
height: 528px;<br />
background-image: url('img/board.jpg');<br />
position: relative;<br />
}<br />
<br />
.square {<br />
width: 62px;<br />
height: 62px;<br />
position: absolute;<br />
background-color: red;<br />
}<br />
</pre><br />
<br />
Explanations:<br />
* With "position: relative" on board, we ensure square elements are positioned relatively to board.<br />
* 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.<br />
<br />
Let's refresh and check our our (beautiful) squares:<br />
<br />
[[File:reversi2.jpg]]<br />
<br />
== The discs ==<br />
<br />
Now, our board is ready to receive some disc tokens!<br />
<br />
At first, we introduce a new 'div' element as a child of "board" to host all these tokens (in our template):<br />
<br />
<pre><br />
<!-- END square --><br />
<br />
<div id="tokens"><br />
</div><br />
</div><br />
</pre><br />
<br />
Then, let's introduce a new piece of art with the discs. We need some transparency here so we are using a png file:<br />
<br />
[[File:tokens.png]]<br />
<br />
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].<br />
<br />
Now, let's separate the disc with some CSS stuff:<br />
<br />
<pre><br />
.token {<br />
width: 56px;<br />
height: 56px;<br />
position: absolute;<br />
background-image: url('img/tokens.png');<br />
}<br />
.tokencolor_ffffff { background-position: 0px 0px; }<br />
.tokencolor_000000 { background-position: -56px 0px; }<br />
</pre><br />
<br />
With this CSS code, we apply the classes "token" and "tokencolor_ffffff" to a div element and we've got a white token. Yeah.<br />
<br />
Note the "position: absolute" which allows us to position tokens on the board and make them "slide" to their positions.<br />
<br />
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".<br />
<br />
In our template file (reversi_reversi.tpl), let's create the piece of HTML needed to display our token:<br />
<br />
<pre><br />
<script type="text/javascript"><br />
<br />
// Templates<br />
<br />
var jstpl_token='<div class="token tokencolor_${color}" id="token_${x_y}"></div>';<br />
<br />
</script><br />
</pre><br />
<br />
Note: we already created the "templates" section for you in the game skeleton.<br />
<br />
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).<br />
<br />
Now, let's create a method in our Javascript code that will make a token appear on the board, using this template:<br />
<br />
<pre><br />
addTokenOnBoard: function( x, y, player )<br />
{<br />
dojo.place( this.format_block( 'jstpl_token', {<br />
x_y: x+'_'+y,<br />
color: this.gamedatas.players[ player ].color<br />
} ) , 'tokens' );<br />
<br />
this.placeOnObject( 'token_'+x+'_'+y, 'overall_player_board_'+player );<br />
this.slideToObject( 'token_'+x+'_'+y, 'square_'+x+'_'+y ).play();<br />
},<br />
</pre><br />
<br />
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.<br />
<br />
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.<br />
<br />
Note: don't forget to call the "play()", otherwise the token remains at its original location.<br />
<br />
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.<br />
<br />
Before we can show a token, we need to set the player colors in the setupNewGame function in reversi.game.php:<br />
<pre><br />
$default_colors = array( "ffffff", "000000" );<br />
</pre><br />
<br />
Now, to test if everything works fine, just call "this.addTokenOnBoard( 2, 2, <your_player_id> )" in your "setup" Javascript method, and reload the page. A token should appear and slide immediately to its position, like this:<br />
<br />
[[File:reversi3.jpg]]<br />
<br />
== The database ==<br />
<br />
We did most of the client-side programming, so let's have a look on the other side now.<br />
<br />
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.<br />
<br />
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.<br />
<br />
[[File:reversi4.jpg]]<br />
<br />
The database model of Reversi is very simple: just one table with the squares of the board. In our dbmodel.sql, we have this:<br />
<br />
<pre><br />
CREATE TABLE IF NOT EXISTS `board` (<br />
`board_x` smallint(5) unsigned NOT NULL,<br />
`board_y` smallint(5) unsigned NOT NULL,<br />
`board_player` int(10) unsigned DEFAULT NULL,<br />
PRIMARY KEY (`board_x`,`board_y`)<br />
) ENGINE=InnoDB;<br />
</pre><br />
<br />
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.<br />
<br />
== Setup the initial game position ==<br />
<br />
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).<br />
<br />
Let's do this:<br />
<br />
<pre><br />
// Init the board<br />
$sql = "INSERT INTO board (board_x,board_y,board_player) VALUES ";<br />
$sql_values = array();<br />
list( $blackplayer_id, $whiteplayer_id ) = array_keys( $players );<br />
for( $x=1; $x<=8; $x++ )<br />
{<br />
for( $y=1; $y<=8; $y++ )<br />
{<br />
$token_value = "NULL";<br />
if( ($x==4 && $y==4) || ($x==5 && $y==5) ) // Initial positions of white player<br />
$token_value = "'$whiteplayer_id'";<br />
else if( ($x==4 && $y==5) || ($x==5 && $y==4) ) // Initial positions of black player<br />
$token_value = "'$blackplayer_id'";<br />
<br />
$sql_values[] = "('$x','$y',$token_value)";<br />
}<br />
}<br />
$sql .= implode( $sql_values, ',' );<br />
self::DbQuery( $sql );<br />
<br />
<br />
// Active first player<br />
self::activeNextPlayer(); <br />
</pre><br />
<br />
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.<br />
<br />
At the end, we call activeNextPlayer to make the first player active at the beginning of the game.<br />
<br />
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):<br />
<br />
<pre><br />
// Get reversi board token<br />
$result['board'] = self::getObjectListFromDB( "SELECT board_x x, board_y y, board_player player<br />
FROM board<br />
WHERE board_player IS NOT NULL" );<br />
</pre><br />
<br />
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.<br />
<br />
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:<br />
<br />
<pre><br />
for( var i in gamedatas.board )<br />
{<br />
var square = gamedatas.board[i];<br />
<br />
if( square.player !== null )<br />
{<br />
this.addTokenOnBoard( square.x, square.y, square.player );<br />
}<br />
}<br />
</pre><br />
<br />
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.<br />
<br />
Reload... and here we are:<br />
<br />
[[File:reversi5.jpg]]<br />
<br />
It starts to smell Reversi here...<br />
<br />
== The game state machine ==<br />
<br />
Now, let's stop our game again, because we are going to start the core game logic.<br />
<br />
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 although. Here's a diagram of our game state machine:<br />
<br />
[[File:reversi6.jpg]]<br />
<br />
And here's our "states.inc.php", according to this diagram:<br />
<br />
<pre><br />
$machinestates = array(<br />
<br />
1 => array(<br />
"name" => "gameSetup",<br />
"description" => clienttranslate("Game setup"),<br />
"type" => "manager",<br />
"action" => "stGameSetup",<br />
"transitions" => array( "" => 10 )<br />
),<br />
<br />
10 => array(<br />
"name" => "playerTurn",<br />
"description" => clienttranslate('${actplayer} must play a disc'),<br />
"descriptionmyturn" => clienttranslate('${you} must play a disc'),<br />
"type" => "activeplayer",<br />
"args" => "argPlayerTurn",<br />
"possibleactions" => array( 'playDisc' ),<br />
"transitions" => array( "playDisc" => 11, "zombiePass" => 11 )<br />
),<br />
<br />
11 => array(<br />
"name" => "nextPlayer",<br />
"type" => "game",<br />
"action" => "stNextPlayer",<br />
"updateGameProgression" => true, <br />
"transitions" => array( "nextTurn" => 10, "cantPlay" => 11, "endGame" => 99 )<br />
),<br />
<br />
99 => array(<br />
"name" => "gameEnd",<br />
"description" => clienttranslate("End of game"),<br />
"type" => "manager",<br />
"action" => "stGameEnd",<br />
"args" => "argGameEnd"<br />
)<br />
<br />
);<br />
</pre><br />
<br />
Now, let's create in reversi.game.php the methods that are declared in this game states description file:<br />
* argPlayerTurn<br />
* stNextPlayer<br />
<br />
... and start a new Reversi game.<br />
<br />
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"):<br />
<br />
[[File:reversi7.jpg]]<br />
<br />
== The rules ==<br />
<br />
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:<br />
* As we just said, to help the player to see where she can play.<br />
* When the player plays, to check if she has the right to play here.<br />
<br />
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:<br />
* 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.<br />
* 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.<br />
<br />
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.<br />
<br />
If you want to look into details, please look at the "utility method" sections of reversi.game.php.<br />
<br />
== Display allowed moves ==<br />
<br />
Now, what we want to do is highlight the squares where the player can place a disc.<br />
<br />
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:<br />
<br />
<pre><br />
<br />
function argPlayerTurn()<br />
{<br />
return array(<br />
'possibleMoves' => self::getPossibleMoves( self::getActivePlayerId() )<br />
);<br />
}<br />
</pre><br />
<br />
We are of course using the "getPossibleMoves" method we just developed.<br />
<br />
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:<br />
<br />
<pre><br />
onEnteringState: function( stateName, args )<br />
{<br />
console.log( 'Entering state: '+stateName );<br />
<br />
switch( stateName )<br />
{<br />
case 'playerTurn':<br />
this.updatePossibleMoves( args.args.possibleMoves );<br />
break;<br />
}<br />
},<br />
</pre><br />
<br />
So, when we are entering into "playerTurn" game state, we are calling our "updatePossibleMoves" method. This method looks like this:<br />
<br />
<pre><br />
updatePossibleMoves: function( possibleMoves )<br />
{<br />
// Remove current possible moves<br />
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );<br />
<br />
for( var x in possibleMoves )<br />
{<br />
for( var y in possibleMoves[ x ] )<br />
{<br />
// x,y is a possible move<br />
dojo.addClass( 'square_'+x+'_'+y, 'possibleMove' );<br />
} <br />
}<br />
<br />
this.addTooltipToClass( 'possibleMove', '', _('Place a disc here') );<br />
},<br />
</pre><br />
<br />
The idea here is that we've created a CSS class ("possibleMove") that can be applied to a "square" element to highlight it:<br />
<pre><br />
.possibleMove {<br />
background-color: white;<br />
opacity: 0.2;<br />
filter:alpha(opacity=20); /* For IE8 and earlier */ <br />
cursor: pointer; <br />
}<br />
</pre><br />
<br />
At first, we remove all "possibleMove" classes currently applied with the very useful combination of "dojo.query" and "removeClass" method.<br />
<br />
Then we loop through all possible moves our PHP "updatePossibleMoves" function created for us, and add the "possibleMove" class to each corresponding square.<br />
<br />
Finally, we use the BGA framework "addTooltipToClass" method to associate a tooltip to all those highlighted squares so that players can understand their meaning.<br />
<br />
And here we are:<br />
<br />
[[File:reversi8.jpg.jpg]]<br />
<br />
== Let's play ==<br />
<br />
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:<br />
* When we click on a "possibleMove" square, send the move to the server.<br />
* Server side, check the move is correct, apply Reversi rules and jump to next player.<br />
* Client side, change the disc position to reflect the move.<br />
<br />
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:<br />
<br />
<pre><br />
dojo.query( '.square' ).connect( 'onclick', this, 'onPlayDisc' );<br />
</pre><br />
<br />
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.<br />
<br />
Here's our "onPlayDisc" method below:<br />
<br />
<pre><br />
onPlayDisc: function( evt )<br />
{<br />
// Stop this event propagation<br />
dojo.stopEvent( evt );<br />
<br />
// Get the cliqued square x and y<br />
// Note: square id format is "square_X_Y"<br />
var coords = evt.currentTarget.id.split('_');<br />
var x = coords[1];<br />
var y = coords[2];<br />
<br />
if( ! dojo.hasClass( 'square_'+x+'_'+y, 'possibleMove' ) )<br />
{<br />
// This is not a possible move => the click does nothing<br />
return ;<br />
}<br />
<br />
if( this.checkAction( 'playDisc' ) ) // Check that this action is possible at this moment<br />
{ <br />
this.ajaxcall( "/reversi/reversi/playDisc.html", {<br />
x:x,<br />
y:y<br />
}, this, function( result ) {} );<br />
} <br />
},<br />
</pre><br />
<br />
What we do here is:<br />
* We stop the propagation of the Javascript "onclick" event. Otherwise, it can lead to random behavior so it's always a good idea.<br />
* We get the x/y coordinates of the square by using "evt.currentTarget.id".<br />
* We check that clicked square has the "possibleMove" class, otherwise we know for sure that we can't play there.<br />
* 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.<br />
* Finally, we make a call to the server using BGA "ajaxcall" method with argument x and y.<br />
<br />
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":<br />
<br />
<pre><br />
public function playDisc()<br />
{<br />
self::setAjaxMode(); <br />
$x = self::getArg( "x", AT_posint, true );<br />
$y = self::getArg( "y", AT_posint, true );<br />
$result = $this->game->playDisc( $x, $y );<br />
self::ajaxResponse( );<br />
}<br />
</pre><br />
<br />
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.<br />
<br />
Now, let's have a look of this playDisc method:<br />
<br />
<pre><br />
function playDisc( $x, $y )<br />
{<br />
// Check that this player is active and that this action is possible at this moment<br />
self::checkAction( 'playDisc' ); <br />
</pre><br />
<br />
... 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).<br />
<br />
<pre><br />
// Now, check if this is a possible move<br />
$board = self::getBoard();<br />
$player_id = self::getActivePlayerId();<br />
$turnedOverDiscs = self::getTurnedOverDiscs( $x, $y, $player_id, $board );<br />
<br />
if( count( $turnedOverDiscs ) > 0 )<br />
{<br />
// This move is possible!<br />
</pre><br />
<br />
...now, we are using the "getTurnedOverDiscs" method again to check that this move is possible.<br />
<br />
<pre><br />
// Let's place a disc at x,y and return all "$returned" discs to the active player<br />
<br />
$sql = "UPDATE board SET board_player='$player_id'<br />
WHERE ( board_x, board_y) IN ( ";<br />
<br />
foreach( $turnedOverDiscs as $turnedOver )<br />
{<br />
$sql .= "('".$turnedOver['x']."','".$turnedOver['y']."'),";<br />
}<br />
$sql .= "('$x','$y') ) ";<br />
<br />
self::DbQuery( $sql );<br />
<br />
</pre><br />
<br />
... we update the database to change the color of all turned over disc + the disc we just placed.<br />
<br />
<pre><br />
// Update scores according to the number of disc on board<br />
$sql = "UPDATE player<br />
SET player_score = (<br />
SELECT COUNT( board_x ) FROM board WHERE board_player=player_id<br />
)";<br />
self::DbQuery( $sql );<br />
<br />
// Statistics<br />
self::incStat( count( $turnedOverDiscs ), "turnedOver", $player_id );<br />
if( ($x==1 && $y==1) || ($x==8 && $y==1) || ($x==1 && $y==8) || ($x==8 && $y==8) )<br />
self::incStat( 1, 'discPlayedOnCorner', $player_id );<br />
else if( $x==1 || $x==8 || $y==1 || $y==8 )<br />
self::incStat( 1, 'discPlayedOnBorder', $player_id );<br />
else if( $x>=3 && $x<=6 && $y>=3 && $y<=6 )<br />
self::incStat( 1, 'discPlayedOnCenter', $player_id );<br />
<br />
</pre><br />
<br />
... now, we update both player score by counting all disc, and we manage game statistics.<br />
<br />
<pre><br />
// Notify<br />
self::notifyAllPlayers( "playDisc", clienttranslate( '${player_name} plays a disc and turns over ${returned_nbr} disc(s)' ), array(<br />
'player_id' => $player_id,<br />
'player_name' => self::getActivePlayerName(),<br />
'returned_nbr' => count( $turnedOverDiscs ),<br />
'x' => $x,<br />
'y' => $y<br />
) );<br />
<br />
self::notifyAllPlayers( "turnOverDiscs", '', array(<br />
'player_id' => $player_id,<br />
'turnedOver' => $turnedOverDiscs<br />
) );<br />
<br />
$newScores = self::getCollectionFromDb( "SELECT player_id, player_score FROM player", true );<br />
self::notifyAllPlayers( "newScores", "", array(<br />
"scores" => $newScores<br />
) );<br />
</pre><br />
<br />
... 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.<br />
<br />
<pre><br />
// Then, go to the next state<br />
$this->gamestate->nextState( 'playDisc' );<br />
}<br />
else<br />
throw new feException( "Impossible move" );<br />
}<br />
</pre><br />
<br />
... 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).<br />
To make the statistics work, we have to initialize them in state.inc.php:<br />
<br />
<pre><br />
// Statistics existing for each player<br />
"player" => array(<br />
<br />
"discPlayedOnCorner" => array( "id"=> 10,<br />
"name" => totranslate("Discs played on a corner"), <br />
"type" => "int" ),<br />
<br />
"discPlayedOnBorder" => array( "id"=> 11,<br />
"name" => totranslate("Discs played on a border"), <br />
"type" => "int" ),<br />
<br />
"discPlayedOnCenter" => array( "id"=> 12,<br />
"name" => totranslate("Discs played on board center part"), <br />
"type" => "int" ),<br />
<br />
"turnedOver" => array( "id"=> 13,<br />
"name" => totranslate("Number of discs turned over"), <br />
"type" => "int" ) <br />
)<br />
</pre><br />
<br />
A last thing to do on the server side is to activate the next player when we enter the "nextPlayer" game state:<br />
<br />
<pre><br />
function stNextPlayer()<br />
{<br />
// Activate next player<br />
$player_id = self::activeNextPlayer();<br />
<br />
self::giveExtraTime( $player_id );<br />
$this->gamestate->nextState( 'nextTurn' );<br />
<br />
}<br />
</pre><br />
<br />
Now, when we play a disc, the rules are checked and the disc appears in the database.<br />
<br />
[[File:reversi9.jpg]]<br />
<br />
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.<br />
<br />
== Make the move appear automatically ==<br />
<br />
Now, what we have to do is process the notifications sent by the server and make the move appear on the interface.<br />
<br />
In our "setupNotifications" method, we register 2 methods for the 2 notifications we created at the previous step ('playDisc' and 'turnOverDiscs'):<br />
<br />
<pre><br />
dojo.subscribe( 'playDisc', this, "notif_playDisc" );<br />
this.notifqueue.setSynchronous( 'playDisc', 500 );<br />
dojo.subscribe( 'turnOverDiscs', this, "notif_turnOverDiscs" );<br />
this.notifqueue.setSynchronous( 'turnOverDiscs', 1500 );<br />
</pre><br />
<br />
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:<br />
* Make a disc slide from the player panel to its place on the board<br />
* (wait 500ms)<br />
* Make all turned over discs blink (and of course turned them over)<br />
* (wait 1500ms)<br />
* Let the next player play.<br />
<br />
Let's have a look now on the "playDisc" notification handler method:<br />
<br />
<pre><br />
notif_playDisc: function( notif )<br />
{<br />
// Remove current possible moves (makes the board more clear)<br />
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' ); <br />
<br />
this.addTokenOnBoard( notif.args.x, notif.args.y, notif.args.player_id );<br />
},<br />
</pre><br />
<br />
No surprise here, we re-used some existing stuff to:<br />
* Remove the highlighted squares.<br />
* Add a new disc on board, coming from player panel.<br />
<br />
Now, here's the method that handles the turnOverDiscs notification:<br />
<br />
<pre><br />
notif_turnOverDiscs: function( notif )<br />
{<br />
// Get the color of the player who is returning the discs<br />
var targetColor = this.gamedatas.players[ notif.args.player_id ].color;<br />
<br />
// Make these discs blink and set them to the specified color<br />
for( var i in notif.args.turnedOver )<br />
{<br />
var token = notif.args.turnedOver[ i ];<br />
<br />
// Make the token blink 2 times<br />
var anim = dojo.fx.chain( [<br />
dojo.fadeOut( { node: 'token_'+token.x+'_'+token.y } ),<br />
dojo.fadeIn( { node: 'token_'+token.x+'_'+token.y } ),<br />
dojo.fadeOut( { <br />
node: 'token_'+token.x+'_'+token.y,<br />
onEnd: function( node ) {<br />
<br />
// Remove any color class<br />
dojo.removeClass( node, [ 'tokencolor_000000', 'tokencolor_ffffff' ] );<br />
// ... and add the good one<br />
dojo.addClass( node, 'tokencolor_'+targetColor );<br />
<br />
} <br />
} ),<br />
dojo.fadeIn( { node: 'token_'+token.x+'_'+token.y } )<br />
<br />
] ); // end of dojo.fx.chain<br />
<br />
// ... and launch the animation<br />
anim.play(); <br />
}<br />
},<br />
</pre><br />
<br />
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].<br />
<br />
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()".</div>Christopheryoderhttp://en.doc.boardgamearena.com/index.php?title=Players_actions:_yourgamename.action.php&diff=1368Players actions: yourgamename.action.php2015-02-05T19:31:52Z<p>Christopheryoder: /* Useful tip: retrieve a list of number */</p>
<hr />
<div><br />
== Purpose of this file ==<br />
<br />
With this file, you define all the players entry points (ie: possible game actions) of your game.<br />
<br />
This file is a sort of "bridge" between the AJAX calls you are doing from your Javascript client side, and your main PHP code in "yourgame.game.php".<br />
<br />
The role of the methods defined in this file is to filter the arguments, eventually to format them a little bit, and then to call a corresponding PHP method from your main game logic ("yourgame.game.php" file).<br />
<br />
Methods in this file must be short: no game logic must be introduced here.<br />
<br />
== Example of typical action method ==<br />
<br />
(from Reversi example)<br />
<br />
<pre><br />
public function playDisc()<br />
{<br />
self::setAjaxMode(); <br />
$x = self::getArg( "x", AT_posint, true );<br />
$y = self::getArg( "y", AT_posint, true );<br />
$result = $this->game->playDisc( $x, $y );<br />
self::ajaxResponse( );<br />
}<br />
</pre><br />
<br />
== Methods to use in action methods ==<br />
<br />
'''function setAjaxMode'''<br />
<br />
Must be use at the beginning of each action method.<br />
<br />
'''function ajaxResponse'''<br />
<br />
Must be use at the end of each action method.<br />
<br />
'''function getArg( $argName, $argType, $mandatory=false, $default=NULL, $argTypeDetails=array(), $bCanFail=false )'''<br />
<br />
This method must be used to retrieve the arguments sent with your AJAX query.<br />
You must NOT use "_GET", "_POST" or equivalent PHP variables to do this, as it is unsafe.<br />
This method use the following arguments:<br />
* argName: the name of the argument to retrieve.<br />
* argType: the type of the argument. You should use one of the following:<br />
'AT_int' for an integer<br />
'AT_posint' for a positive integer <br />
'AT_float' for a float<br />
'AT_bool' for 1/0/true/false<br />
'AT_enum' for an enumeration (argTypeDetails list the possible values as an array)<br />
'AT_alphanum' for a string with 0-9a-zA-Z_ and space<br />
'AT_numberlist' for a list of several numbers separated with "," or ";" (ex: exemple: 1,4;2,3;-1,2).<br />
* mandatory: specify "true" if the argument is mandatory.<br />
* default: if mandatory=false, you can specify here a default value in case the argument is not present.<br />
* argTypeDetails: see AT_enum above.<br />
* bCanFail: if true, specify that it may be possible that the argument won't be of the type specified by argType (and then do not log this as a fatal error in the system, and return a standard exception to the player).<br />
<br />
<br />
'''function isArg( $argName )'''<br />
<br />
This is a useful method when you only want to check if an argument is present or not present in your AJAX request (and don't care of the value.<br />
<br />
It returns "true" or "false" whether "argName" has been specified as an argument of the AJAX request or not.<br />
<br />
== Useful tip: retrieve a list of numbers ==<br />
<br />
If your Javascript sends a list of integers separated by ";" (ex: "1;2;3;4") as an argument, you can transform them in a PHP array with the following:<br />
<br />
<pre><br />
public function playCards()<br />
{<br />
self::setAjaxMode(); <br />
<br />
$card_ids_raw = self::getArg( "card_ids", AT_numberlist, true );<br />
<br />
// Removing last ';' if exists<br />
if( substr( $card_ids_raw, -1 ) == ';' )<br />
$card_ids_raw = substr( $card_ids_raw, 0, -1 );<br />
if( $card_ids_raw == '' )<br />
$card_ids = array();<br />
else<br />
$card_ids = explode( ';', $card_ids_raw );<br />
<br />
$this->game->playCards( $card_ids );<br />
self::ajaxResponse( );<br />
}<br />
</pre></div>Christopheryoderhttp://en.doc.boardgamearena.com/index.php?title=Tutorial_reversi&diff=1367Tutorial reversi2015-02-05T16:51:56Z<p>Christopheryoder: /* The rules */</p>
<hr />
<div><br />
== Introduction ==<br />
<br />
Using this tutorial, you can build a complete working game on the BGA environment: Reversi.<br />
<br />
Before you read this tutorial, you must:<br />
* Read the overall presentations of the BGA Framework ([[Studio|see here]]).<br />
* Know the [http://en.wikipedia.org/wiki/Reversi#Rules rules of Reversi].<br />
* Know the languages used on BGA: PHP, SQL, HTML, CSS, Javascript.<br />
<br />
== Create your first game ==<br />
<br />
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 this 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.<br />
<br />
Thus, you can start a "Reversi" game, and arrive on a void, empty game. Yeah.<br />
<br />
== Let it look like Reversi ==<br />
<br />
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.<br />
<br />
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).<br />
<br />
For Reversi, it's useless to have a 750x750px board - much too big, so we choose this one which fit perfectly (536x528):<br />
<br />
[[File:Board.jpg]]<br />
<br />
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.<br />
<br />
Now, let's make it appears on our game:<br />
* upload board.jpg in your "img/" directory.<br />
* edit "reversi_reversi.tpl" to add a 'div' for your board:<br />
<br />
<pre><br />
<div id="board"><br />
</div><br />
</pre><br />
<br />
* edit your reversi.css file to transform it into a visible board:<br />
<br />
#board {<br />
width: 536px;<br />
height: 528px;<br />
background-image: url('img/board.jpg');<br />
}<br />
<br />
Refresh your page. Here's your board:<br />
<br />
[[File:reversi1.jpg]]<br />
<br />
== Make the squares appears ==<br />
<br />
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. <br />
Obviously, we need 64 squares. To avoid writing 64 'div' elements on our template, we are going to use the "block" feature.<br />
<br />
Let's modify our template like this:<br />
<br />
<pre><br />
<div id="board"><br />
<!-- BEGIN square --><br />
<div id="square_{X}_{Y}" class="square" style="left: {LEFT}px; top: {TOP}px;"></div><br />
<!-- END square --><br />
</div><br />
</pre><br />
<br />
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.<br />
<br />
Let's do it in our "reversi.view.php" file:<br />
<br />
<pre><br />
$this->page->begin_block( "reversi_reversi", "square" );<br />
<br />
$hor_scale = 64.8;<br />
$ver_scale = 64.4;<br />
for( $x=1; $x<=8; $x++ )<br />
{<br />
for( $y=1; $y<=8; $y++ )<br />
{<br />
$this->page->insert_block( "square", array(<br />
'X' => $x,<br />
'Y' => $y,<br />
'LEFT' => round( ($x-1)*$hor_scale+10 ),<br />
'TOP' => round( ($y-1)*$ver_scale+7 )<br />
) );<br />
} <br />
}<br />
</pre><br />
<br />
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.<br />
<br />
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:<br />
<br />
<pre><br />
#board {<br />
width: 536px;<br />
height: 528px;<br />
background-image: url('img/board.jpg');<br />
position: relative;<br />
}<br />
<br />
.square {<br />
width: 62px;<br />
height: 62px;<br />
position: absolute;<br />
background-color: red;<br />
}<br />
</pre><br />
<br />
Explanations:<br />
* With "position: relative" on board, we ensure square elements are positioned relatively to board.<br />
* 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.<br />
<br />
Let's refresh and check our our (beautiful) squares:<br />
<br />
[[File:reversi2.jpg]]<br />
<br />
== The discs ==<br />
<br />
Now, our board is ready to receive some disc tokens!<br />
<br />
At first, we introduce a new 'div' element as a child of "board" to host all these tokens (in our template):<br />
<br />
<pre><br />
<!-- END square --><br />
<br />
<div id="tokens"><br />
</div><br />
</div><br />
</pre><br />
<br />
Then, let's introduce a new piece of art with the discs. We need some transparency here so we are using a png file:<br />
<br />
[[File:tokens.png]]<br />
<br />
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].<br />
<br />
Now, let's separate the disc with some CSS stuff:<br />
<br />
<pre><br />
.token {<br />
width: 56px;<br />
height: 56px;<br />
position: absolute;<br />
background-image: url('img/tokens.png');<br />
}<br />
.tokencolor_ffffff { background-position: 0px 0px; }<br />
.tokencolor_000000 { background-position: -56px 0px; }<br />
</pre><br />
<br />
With this CSS code, we apply the classes "token" and "tokencolor_ffffff" to a div element and we've got a white token. Yeah.<br />
<br />
Note the "position: absolute" which allows us to position tokens on the board and make them "slide" to their positions.<br />
<br />
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".<br />
<br />
In our template file (reversi_reversi.tpl), let's create the piece of HTML needed to display our token:<br />
<br />
<pre><br />
<script type="text/javascript"><br />
<br />
// Templates<br />
<br />
var jstpl_token='<div class="token tokencolor_${color}" id="token_${x_y}"></div>';<br />
<br />
</script><br />
</pre><br />
<br />
Note: we already created the "templates" section for you in the game skeleton.<br />
<br />
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).<br />
<br />
Now, let's create a method in our Javascript code that will make a token appear on the board, using this template:<br />
<br />
<pre><br />
addTokenOnBoard: function( x, y, player )<br />
{<br />
dojo.place( this.format_block( 'jstpl_token', {<br />
x_y: x+'_'+y,<br />
color: this.gamedatas.players[ player ].color<br />
} ) , 'tokens' );<br />
<br />
this.placeOnObject( 'token_'+x+'_'+y, 'overall_player_board_'+player );<br />
this.slideToObject( 'token_'+x+'_'+y, 'square_'+x+'_'+y ).play();<br />
},<br />
</pre><br />
<br />
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.<br />
<br />
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.<br />
<br />
Note: don't forget to call the "play()", otherwise the token remains at its original location.<br />
<br />
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.<br />
<br />
Before we can show a token, we need to set the player colors in the setupNewGame function in reversi.game.php:<br />
<pre><br />
$default_colors = array( "ffffff", "000000" );<br />
</pre><br />
<br />
Now, to test if everything works fine, just call "this.addTokenOnBoard( 2, 2, <your_player_id> )" in your "setup" Javascript method, and reload the page. A token should appear and slide immediately to its position, like this:<br />
<br />
[[File:reversi3.jpg]]<br />
<br />
== The database ==<br />
<br />
We did most of the client-side programming, so let's have a look on the other side now.<br />
<br />
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.<br />
<br />
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.<br />
<br />
[[File:reversi4.jpg]]<br />
<br />
The database model of Reversi is very simple: just one table with the squares of the board. In our dbmodel.sql, we have this:<br />
<br />
<pre><br />
CREATE TABLE IF NOT EXISTS `board` (<br />
`board_x` smallint(5) unsigned NOT NULL,<br />
`board_y` smallint(5) unsigned NOT NULL,<br />
`board_player` int(10) unsigned DEFAULT NULL,<br />
PRIMARY KEY (`board_x`,`board_y`)<br />
) ENGINE=InnoDB;<br />
</pre><br />
<br />
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.<br />
<br />
== Setup the initial game position ==<br />
<br />
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).<br />
<br />
Let's do this:<br />
<br />
<pre><br />
// Init the board<br />
$sql = "INSERT INTO board (board_x,board_y,board_player) VALUES ";<br />
$sql_values = array();<br />
list( $blackplayer_id, $whiteplayer_id ) = array_keys( $players );<br />
for( $x=1; $x<=8; $x++ )<br />
{<br />
for( $y=1; $y<=8; $y++ )<br />
{<br />
$token_value = "NULL";<br />
if( ($x==4 && $y==4) || ($x==5 && $y==5) ) // Initial positions of white player<br />
$token_value = "'$whiteplayer_id'";<br />
else if( ($x==4 && $y==5) || ($x==5 && $y==4) ) // Initial positions of black player<br />
$token_value = "'$blackplayer_id'";<br />
<br />
$sql_values[] = "('$x','$y',$token_value)";<br />
}<br />
}<br />
$sql .= implode( $sql_values, ',' );<br />
self::DbQuery( $sql );<br />
<br />
<br />
// Active first player<br />
self::activeNextPlayer(); <br />
</pre><br />
<br />
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.<br />
<br />
At the end, we call activeNextPlayer to make the first player active at the beginning of the game.<br />
<br />
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):<br />
<br />
<pre><br />
// Get reversi board token<br />
$result['board'] = self::getObjectListFromDB( "SELECT board_x x, board_y y, board_player player<br />
FROM board<br />
WHERE board_player IS NOT NULL" );<br />
</pre><br />
<br />
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.<br />
<br />
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:<br />
<br />
<pre><br />
for( var i in gamedatas.board )<br />
{<br />
var square = gamedatas.board[i];<br />
<br />
if( square.player !== null )<br />
{<br />
this.addTokenOnBoard( square.x, square.y, square.player );<br />
}<br />
}<br />
</pre><br />
<br />
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.<br />
<br />
Reload... and here we are:<br />
<br />
[[File:reversi5.jpg]]<br />
<br />
It starts to smell Reversi here...<br />
<br />
== The game state machine ==<br />
<br />
Now, let's stop our game again, because we are going to start the core game logic.<br />
<br />
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 although. Here's a diagram of our game state machine:<br />
<br />
[[File:reversi6.jpg]]<br />
<br />
And here's our "states.inc.php", according to this diagram:<br />
<br />
<pre><br />
$machinestates = array(<br />
<br />
1 => array(<br />
"name" => "gameSetup",<br />
"description" => clienttranslate("Game setup"),<br />
"type" => "manager",<br />
"action" => "stGameSetup",<br />
"transitions" => array( "" => 10 )<br />
),<br />
<br />
10 => array(<br />
"name" => "playerTurn",<br />
"description" => clienttranslate('${actplayer} must play a disc'),<br />
"descriptionmyturn" => clienttranslate('${you} must play a disc'),<br />
"type" => "activeplayer",<br />
"args" => "argPlayerTurn",<br />
"possibleactions" => array( 'playDisc' ),<br />
"transitions" => array( "playDisc" => 11, "zombiePass" => 11 )<br />
),<br />
<br />
11 => array(<br />
"name" => "nextPlayer",<br />
"type" => "game",<br />
"action" => "stNextPlayer",<br />
"updateGameProgression" => true, <br />
"transitions" => array( "nextTurn" => 10, "cantPlay" => 11, "endGame" => 99 )<br />
),<br />
<br />
99 => array(<br />
"name" => "gameEnd",<br />
"description" => clienttranslate("End of game"),<br />
"type" => "manager",<br />
"action" => "stGameEnd",<br />
"args" => "argGameEnd"<br />
)<br />
<br />
);<br />
</pre><br />
<br />
Now, let's create in reversi.game.php the methods that are declared in this game states description file:<br />
* argPlayerTurn<br />
* stNextPlayer<br />
<br />
... and start a new Reversi game.<br />
<br />
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"):<br />
<br />
[[File:reversi7.jpg]]<br />
<br />
== The rules ==<br />
<br />
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:<br />
* As we just said, to help the player to see where she can play.<br />
* When the player plays, to check if she has the right to play here.<br />
<br />
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:<br />
* 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.<br />
* 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.<br />
<br />
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.<br />
<br />
If you want to look into details, please look at the "utility method" sections of reversi.game.php.<br />
<br />
== Display allowed moves ==<br />
<br />
Now, what we want to do is highlight the squares where the player can place a disc.<br />
<br />
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:<br />
<br />
<pre><br />
<br />
function argPlayerTurn()<br />
{<br />
return array(<br />
'possibleMoves' => self::getPossibleMoves( self::getActivePlayerId() )<br />
);<br />
}<br />
</pre><br />
<br />
We are of course using the "getPossibleMoves" method we just developed.<br />
<br />
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:<br />
<br />
<pre><br />
onEnteringState: function( stateName, args )<br />
{<br />
console.log( 'Entering state: '+stateName );<br />
<br />
switch( stateName )<br />
{<br />
case 'playerTurn':<br />
this.updatePossibleMoves( args.args.possibleMoves );<br />
break;<br />
}<br />
},<br />
</pre><br />
<br />
So, when we are entering into "playerTurn" game state, we are calling our "updatePossibleMoves" method. This method looks like this:<br />
<br />
<pre><br />
updatePossibleMoves: function( possibleMoves )<br />
{<br />
// Remove current possible moves<br />
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );<br />
<br />
for( var x in possibleMoves )<br />
{<br />
for( var y in possibleMoves[ x ] )<br />
{<br />
// x,y is a possible move<br />
dojo.addClass( 'square_'+x+'_'+y, 'possibleMove' );<br />
} <br />
}<br />
<br />
this.addTooltipToClass( 'possibleMove', '', _('Place a disc here') );<br />
},<br />
</pre><br />
<br />
The idea here is that we've created a CSS class ("possibleMove") that can be applied to a "square" element to highlight it:<br />
<pre><br />
.possibleMove {<br />
background-color: white;<br />
opacity: 0.2;<br />
filter:alpha(opacity=20); /* For IE8 and earlier */ <br />
cursor: pointer; <br />
}<br />
</pre><br />
<br />
At first, we remove all "possibleMove" classes currently applied with the very useful combination of "dojo.query" and "removeClass" method.<br />
<br />
Then we loop through all possible moves our PHP "updatePossibleMoves" function created for us, and add the "possibleMove" class to each corresponding square.<br />
<br />
Finally, we use the BGA framework "addTooltipToClass" method to associate a tooltip to all those highlighted squares so that players can understand their meaning.<br />
<br />
And here we are:<br />
<br />
[[File:reversi8.jpg.jpg]]<br />
<br />
== Let's play ==<br />
<br />
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:<br />
* When we click on a "possibleMove" square, send the move to the server.<br />
* Server side, check the move is correct, apply Reversi rules and jump to next player.<br />
* Client side, change the disc position to reflect the move.<br />
<br />
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:<br />
<br />
<pre><br />
dojo.query( '.square' ).connect( 'onclick', this, 'onPlayDisc' );<br />
</pre><br />
<br />
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.<br />
<br />
Here's our "onPlayDisc" method below:<br />
<br />
<pre><br />
onPlayDisc: function( evt )<br />
{<br />
// Stop this event propagation<br />
dojo.stopEvent( evt );<br />
<br />
// Get the cliqued square x and y<br />
// Note: square id format is "square_X_Y"<br />
var coords = evt.currentTarget.id.split('_');<br />
var x = coords[1];<br />
var y = coords[2];<br />
<br />
if( ! dojo.hasClass( 'square_'+x+'_'+y, 'possibleMove' ) )<br />
{<br />
// This is not a possible move => the click does nothing<br />
return ;<br />
}<br />
<br />
if( this.checkAction( 'playDisc' ) ) // Check that this action is possible at this moment<br />
{ <br />
this.ajaxcall( "/reversi/reversi/playDisc.html", {<br />
x:x,<br />
y:y<br />
}, this, function( result ) {} );<br />
} <br />
},<br />
</pre><br />
<br />
What we do here is:<br />
* We stop the propagation of the Javascript "onclick" event. Otherwise, it can lead to random behavior so it's always a good idea.<br />
* We get the x/y coordinates of the square by using "evt.currentTarget.id".<br />
* We check that clicked square has the "possibleMove" class, otherwise we know for sure that we can't play there.<br />
* 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.<br />
* Finally, we make a call to the server using BGA "ajaxcall" method with argument x and y.<br />
<br />
Now, we have to manage this "playDisc" action on server side. At first, we introduce a "playDisc" entry point in our "reversi.action.php":<br />
<br />
<pre><br />
public function playDisc()<br />
{<br />
self::setAjaxMode(); <br />
$x = self::getArg( "x", AT_posint, true );<br />
$y = self::getArg( "y", AT_posint, true );<br />
$result = $this->game->playDisc( $x, $y );<br />
self::ajaxResponse( );<br />
}<br />
</pre><br />
<br />
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.<br />
<br />
Now, let's have a look of this playDisc method:<br />
<br />
<pre><br />
function playDisc( $x, $y )<br />
{<br />
// Check that this player is active and that this action is possible at this moment<br />
self::checkAction( 'playDisc' ); <br />
</pre><br />
<br />
... 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).<br />
<br />
<pre><br />
// Now, check if this is a possible move<br />
$board = self::getBoard();<br />
$player_id = self::getActivePlayerId();<br />
$turnedOverDiscs = self::getTurnedOverDiscs( $x, $y, $player_id, $board );<br />
<br />
if( count( $turnedOverDiscs ) > 0 )<br />
{<br />
// This move is possible!<br />
</pre><br />
<br />
...now, we are using the "getTurnedOverDiscs" method again to check that this move is possible.<br />
<br />
<pre><br />
// Let's place a disc at x,y and return all "$returned" discs to the active player<br />
<br />
$sql = "UPDATE board SET board_player='$player_id'<br />
WHERE ( board_x, board_y) IN ( ";<br />
<br />
foreach( $turnedOverDiscs as $turnedOver )<br />
{<br />
$sql .= "('".$turnedOver['x']."','".$turnedOver['y']."'),";<br />
}<br />
$sql .= "('$x','$y') ) ";<br />
<br />
self::DbQuery( $sql );<br />
<br />
</pre><br />
<br />
... we update the database to change the color of all turned over disc + the disc we just placed.<br />
<br />
<pre><br />
// Update scores according to the number of disc on board<br />
$sql = "UPDATE player<br />
SET player_score = (<br />
SELECT COUNT( board_x ) FROM board WHERE board_player=player_id<br />
)";<br />
self::DbQuery( $sql );<br />
<br />
// Statistics<br />
self::incStat( count( $turnedOverDiscs ), "turnedOver", $player_id );<br />
if( ($x==1 && $y==1) || ($x==8 && $y==1) || ($x==1 && $y==8) || ($x==8 && $y==8) )<br />
self::incStat( 1, 'discPlayedOnCorner', $player_id );<br />
else if( $x==1 || $x==8 || $y==1 || $y==8 )<br />
self::incStat( 1, 'discPlayedOnBorder', $player_id );<br />
else if( $x>=3 && $x<=6 && $y>=3 && $y<=6 )<br />
self::incStat( 1, 'discPlayedOnCenter', $player_id );<br />
<br />
</pre><br />
<br />
... now, we update both player score by counting all disc, and we manage game statistics.<br />
<br />
<pre><br />
// Notify<br />
self::notifyAllPlayers( "playDisc", clienttranslate( '${player_name} plays a disc and turns over ${returned_nbr} disc(s)' ), array(<br />
'player_id' => $player_id,<br />
'player_name' => self::getActivePlayerName(),<br />
'returned_nbr' => count( $turnedOverDiscs ),<br />
'x' => $x,<br />
'y' => $y<br />
) );<br />
<br />
self::notifyAllPlayers( "turnOverDiscs", '', array(<br />
'player_id' => $player_id,<br />
'turnedOver' => $turnedOverDiscs<br />
) );<br />
<br />
$newScores = self::getCollectionFromDb( "SELECT player_id, player_score FROM player", true );<br />
self::notifyAllPlayers( "newScores", "", array(<br />
"scores" => $newScores<br />
) );<br />
</pre><br />
<br />
... 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.<br />
<br />
<pre><br />
// Then, go to the next state<br />
$this->gamestate->nextState( 'playDisc' );<br />
}<br />
else<br />
throw new feException( "Impossible move" );<br />
}<br />
</pre><br />
<br />
... 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).<br />
To make the statistics work, we have to initialize them in state.inc.php:<br />
<br />
<pre><br />
// Statistics existing for each player<br />
"player" => array(<br />
<br />
"discPlayedOnCorner" => array( "id"=> 10,<br />
"name" => totranslate("Discs played on a corner"), <br />
"type" => "int" ),<br />
<br />
"discPlayedOnBorder" => array( "id"=> 11,<br />
"name" => totranslate("Discs played on a border"), <br />
"type" => "int" ),<br />
<br />
"discPlayedOnCenter" => array( "id"=> 12,<br />
"name" => totranslate("Discs played on board center part"), <br />
"type" => "int" ),<br />
<br />
"turnedOver" => array( "id"=> 13,<br />
"name" => totranslate("Number of discs turned over"), <br />
"type" => "int" ) <br />
)<br />
</pre><br />
<br />
A last thing to do on the server side is to activate the next player when we enter the "nextPlayer" game state:<br />
<br />
<pre><br />
function stNextPlayer()<br />
{<br />
// Activate next player<br />
$player_id = self::activeNextPlayer();<br />
<br />
self::giveExtraTime( $player_id );<br />
$this->gamestate->nextState( 'nextTurn' );<br />
<br />
}<br />
</pre><br />
<br />
Now, when we play a disc, the rules are checked and the disc appears in the database.<br />
<br />
[[File:reversi9.jpg]]<br />
<br />
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.<br />
<br />
== Make the move appear automatically ==<br />
<br />
Now, what we have to do is process the notifications sent by the server and make the move appear on the interface.<br />
<br />
In our "setupNotifications" method, we register 2 methods for the 2 notifications we created at the previous step ('playDisc' and 'turnOverDiscs'):<br />
<br />
<pre><br />
dojo.subscribe( 'playDisc', this, "notif_playDisc" );<br />
this.notifqueue.setSynchronous( 'playDisc', 500 );<br />
dojo.subscribe( 'turnOverDiscs', this, "notif_turnOverDiscs" );<br />
this.notifqueue.setSynchronous( 'turnOverDiscs', 1500 );<br />
</pre><br />
<br />
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:<br />
* Make a disc slide from the player panel to its place on the board<br />
* (wait 500ms)<br />
* Make all turned over discs blink (and of course turned them over)<br />
* (wait 1500ms)<br />
* Let the next player play.<br />
<br />
Let's have a look now on the "playDisc" notification handler method:<br />
<br />
<pre><br />
notif_playDisc: function( notif )<br />
{<br />
// Remove current possible moves (makes the board more clear)<br />
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' ); <br />
<br />
this.addTokenOnBoard( notif.args.x, notif.args.y, notif.args.player_id );<br />
},<br />
</pre><br />
<br />
No surprise here, we re-used some existing stuff to:<br />
* Remove the highlighted squares.<br />
* Add a new disc on board, coming from player panel.<br />
<br />
Now, here's the method that handles the turnOverDiscs notification:<br />
<br />
<pre><br />
notif_turnOverDiscs: function( notif )<br />
{<br />
// Get the color of the player who is returning the discs<br />
var targetColor = this.gamedatas.players[ notif.args.player_id ].color;<br />
<br />
// Make these discs blink and set them to the specified color<br />
for( var i in notif.args.turnedOver )<br />
{<br />
var token = notif.args.turnedOver[ i ];<br />
<br />
// Make the token blink 2 times<br />
var anim = dojo.fx.chain( [<br />
dojo.fadeOut( { node: 'token_'+token.x+'_'+token.y } ),<br />
dojo.fadeIn( { node: 'token_'+token.x+'_'+token.y } ),<br />
dojo.fadeOut( { <br />
node: 'token_'+token.x+'_'+token.y,<br />
onEnd: function( node ) {<br />
<br />
// Remove any color class<br />
dojo.removeClass( node, [ 'tokencolor_000000', 'tokencolor_ffffff' ] );<br />
// ... and add the good one<br />
dojo.addClass( node, 'tokencolor_'+targetColor );<br />
<br />
} <br />
} ),<br />
dojo.fadeIn( { node: 'token_'+token.x+'_'+token.y } )<br />
<br />
] ); // end of dojo.fx.chain<br />
<br />
// ... and launch the animation<br />
anim.play(); <br />
}<br />
},<br />
</pre><br />
<br />
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].<br />
<br />
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()".</div>Christopheryoderhttp://en.doc.boardgamearena.com/index.php?title=Tutorial_reversi&diff=1366Tutorial reversi2015-02-05T16:51:05Z<p>Christopheryoder: /* The rules */</p>
<hr />
<div><br />
== Introduction ==<br />
<br />
Using this tutorial, you can build a complete working game on the BGA environment: Reversi.<br />
<br />
Before you read this tutorial, you must:<br />
* Read the overall presentations of the BGA Framework ([[Studio|see here]]).<br />
* Know the [http://en.wikipedia.org/wiki/Reversi#Rules rules of Reversi].<br />
* Know the languages used on BGA: PHP, SQL, HTML, CSS, Javascript.<br />
<br />
== Create your first game ==<br />
<br />
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 this 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.<br />
<br />
Thus, you can start a "Reversi" game, and arrive on a void, empty game. Yeah.<br />
<br />
== Let it look like Reversi ==<br />
<br />
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.<br />
<br />
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).<br />
<br />
For Reversi, it's useless to have a 750x750px board - much too big, so we choose this one which fit perfectly (536x528):<br />
<br />
[[File:Board.jpg]]<br />
<br />
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.<br />
<br />
Now, let's make it appears on our game:<br />
* upload board.jpg in your "img/" directory.<br />
* edit "reversi_reversi.tpl" to add a 'div' for your board:<br />
<br />
<pre><br />
<div id="board"><br />
</div><br />
</pre><br />
<br />
* edit your reversi.css file to transform it into a visible board:<br />
<br />
#board {<br />
width: 536px;<br />
height: 528px;<br />
background-image: url('img/board.jpg');<br />
}<br />
<br />
Refresh your page. Here's your board:<br />
<br />
[[File:reversi1.jpg]]<br />
<br />
== Make the squares appears ==<br />
<br />
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. <br />
Obviously, we need 64 squares. To avoid writing 64 'div' elements on our template, we are going to use the "block" feature.<br />
<br />
Let's modify our template like this:<br />
<br />
<pre><br />
<div id="board"><br />
<!-- BEGIN square --><br />
<div id="square_{X}_{Y}" class="square" style="left: {LEFT}px; top: {TOP}px;"></div><br />
<!-- END square --><br />
</div><br />
</pre><br />
<br />
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.<br />
<br />
Let's do it in our "reversi.view.php" file:<br />
<br />
<pre><br />
$this->page->begin_block( "reversi_reversi", "square" );<br />
<br />
$hor_scale = 64.8;<br />
$ver_scale = 64.4;<br />
for( $x=1; $x<=8; $x++ )<br />
{<br />
for( $y=1; $y<=8; $y++ )<br />
{<br />
$this->page->insert_block( "square", array(<br />
'X' => $x,<br />
'Y' => $y,<br />
'LEFT' => round( ($x-1)*$hor_scale+10 ),<br />
'TOP' => round( ($y-1)*$ver_scale+7 )<br />
) );<br />
} <br />
}<br />
</pre><br />
<br />
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.<br />
<br />
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:<br />
<br />
<pre><br />
#board {<br />
width: 536px;<br />
height: 528px;<br />
background-image: url('img/board.jpg');<br />
position: relative;<br />
}<br />
<br />
.square {<br />
width: 62px;<br />
height: 62px;<br />
position: absolute;<br />
background-color: red;<br />
}<br />
</pre><br />
<br />
Explanations:<br />
* With "position: relative" on board, we ensure square elements are positioned relatively to board.<br />
* 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.<br />
<br />
Let's refresh and check our our (beautiful) squares:<br />
<br />
[[File:reversi2.jpg]]<br />
<br />
== The discs ==<br />
<br />
Now, our board is ready to receive some disc tokens!<br />
<br />
At first, we introduce a new 'div' element as a child of "board" to host all these tokens (in our template):<br />
<br />
<pre><br />
<!-- END square --><br />
<br />
<div id="tokens"><br />
</div><br />
</div><br />
</pre><br />
<br />
Then, let's introduce a new piece of art with the discs. We need some transparency here so we are using a png file:<br />
<br />
[[File:tokens.png]]<br />
<br />
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].<br />
<br />
Now, let's separate the disc with some CSS stuff:<br />
<br />
<pre><br />
.token {<br />
width: 56px;<br />
height: 56px;<br />
position: absolute;<br />
background-image: url('img/tokens.png');<br />
}<br />
.tokencolor_ffffff { background-position: 0px 0px; }<br />
.tokencolor_000000 { background-position: -56px 0px; }<br />
</pre><br />
<br />
With this CSS code, we apply the classes "token" and "tokencolor_ffffff" to a div element and we've got a white token. Yeah.<br />
<br />
Note the "position: absolute" which allows us to position tokens on the board and make them "slide" to their positions.<br />
<br />
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".<br />
<br />
In our template file (reversi_reversi.tpl), let's create the piece of HTML needed to display our token:<br />
<br />
<pre><br />
<script type="text/javascript"><br />
<br />
// Templates<br />
<br />
var jstpl_token='<div class="token tokencolor_${color}" id="token_${x_y}"></div>';<br />
<br />
</script><br />
</pre><br />
<br />
Note: we already created the "templates" section for you in the game skeleton.<br />
<br />
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).<br />
<br />
Now, let's create a method in our Javascript code that will make a token appear on the board, using this template:<br />
<br />
<pre><br />
addTokenOnBoard: function( x, y, player )<br />
{<br />
dojo.place( this.format_block( 'jstpl_token', {<br />
x_y: x+'_'+y,<br />
color: this.gamedatas.players[ player ].color<br />
} ) , 'tokens' );<br />
<br />
this.placeOnObject( 'token_'+x+'_'+y, 'overall_player_board_'+player );<br />
this.slideToObject( 'token_'+x+'_'+y, 'square_'+x+'_'+y ).play();<br />
},<br />
</pre><br />
<br />
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.<br />
<br />
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.<br />
<br />
Note: don't forget to call the "play()", otherwise the token remains at its original location.<br />
<br />
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.<br />
<br />
Before we can show a token, we need to set the player colors in the setupNewGame function in reversi.game.php:<br />
<pre><br />
$default_colors = array( "ffffff", "000000" );<br />
</pre><br />
<br />
Now, to test if everything works fine, just call "this.addTokenOnBoard( 2, 2, <your_player_id> )" in your "setup" Javascript method, and reload the page. A token should appear and slide immediately to its position, like this:<br />
<br />
[[File:reversi3.jpg]]<br />
<br />
== The database ==<br />
<br />
We did most of the client-side programming, so let's have a look on the other side now.<br />
<br />
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.<br />
<br />
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.<br />
<br />
[[File:reversi4.jpg]]<br />
<br />
The database model of Reversi is very simple: just one table with the squares of the board. In our dbmodel.sql, we have this:<br />
<br />
<pre><br />
CREATE TABLE IF NOT EXISTS `board` (<br />
`board_x` smallint(5) unsigned NOT NULL,<br />
`board_y` smallint(5) unsigned NOT NULL,<br />
`board_player` int(10) unsigned DEFAULT NULL,<br />
PRIMARY KEY (`board_x`,`board_y`)<br />
) ENGINE=InnoDB;<br />
</pre><br />
<br />
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.<br />
<br />
== Setup the initial game position ==<br />
<br />
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).<br />
<br />
Let's do this:<br />
<br />
<pre><br />
// Init the board<br />
$sql = "INSERT INTO board (board_x,board_y,board_player) VALUES ";<br />
$sql_values = array();<br />
list( $blackplayer_id, $whiteplayer_id ) = array_keys( $players );<br />
for( $x=1; $x<=8; $x++ )<br />
{<br />
for( $y=1; $y<=8; $y++ )<br />
{<br />
$token_value = "NULL";<br />
if( ($x==4 && $y==4) || ($x==5 && $y==5) ) // Initial positions of white player<br />
$token_value = "'$whiteplayer_id'";<br />
else if( ($x==4 && $y==5) || ($x==5 && $y==4) ) // Initial positions of black player<br />
$token_value = "'$blackplayer_id'";<br />
<br />
$sql_values[] = "('$x','$y',$token_value)";<br />
}<br />
}<br />
$sql .= implode( $sql_values, ',' );<br />
self::DbQuery( $sql );<br />
<br />
<br />
// Active first player<br />
self::activeNextPlayer(); <br />
</pre><br />
<br />
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.<br />
<br />
At the end, we call activeNextPlayer to make the first player active at the beginning of the game.<br />
<br />
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):<br />
<br />
<pre><br />
// Get reversi board token<br />
$result['board'] = self::getObjectListFromDB( "SELECT board_x x, board_y y, board_player player<br />
FROM board<br />
WHERE board_player IS NOT NULL" );<br />
</pre><br />
<br />
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.<br />
<br />
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:<br />
<br />
<pre><br />
for( var i in gamedatas.board )<br />
{<br />
var square = gamedatas.board[i];<br />
<br />
if( square.player !== null )<br />
{<br />
this.addTokenOnBoard( square.x, square.y, square.player );<br />
}<br />
}<br />
</pre><br />
<br />
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.<br />
<br />
Reload... and here we are:<br />
<br />
[[File:reversi5.jpg]]<br />
<br />
It starts to smell Reversi here...<br />
<br />
== The game state machine ==<br />
<br />
Now, let's stop our game again, because we are going to start the core game logic.<br />
<br />
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 although. Here's a diagram of our game state machine:<br />
<br />
[[File:reversi6.jpg]]<br />
<br />
And here's our "states.inc.php", according to this diagram:<br />
<br />
<pre><br />
$machinestates = array(<br />
<br />
1 => array(<br />
"name" => "gameSetup",<br />
"description" => clienttranslate("Game setup"),<br />
"type" => "manager",<br />
"action" => "stGameSetup",<br />
"transitions" => array( "" => 10 )<br />
),<br />
<br />
10 => array(<br />
"name" => "playerTurn",<br />
"description" => clienttranslate('${actplayer} must play a disc'),<br />
"descriptionmyturn" => clienttranslate('${you} must play a disc'),<br />
"type" => "activeplayer",<br />
"args" => "argPlayerTurn",<br />
"possibleactions" => array( 'playDisc' ),<br />
"transitions" => array( "playDisc" => 11, "zombiePass" => 11 )<br />
),<br />
<br />
11 => array(<br />
"name" => "nextPlayer",<br />
"type" => "game",<br />
"action" => "stNextPlayer",<br />
"updateGameProgression" => true, <br />
"transitions" => array( "nextTurn" => 10, "cantPlay" => 11, "endGame" => 99 )<br />
),<br />
<br />
99 => array(<br />
"name" => "gameEnd",<br />
"description" => clienttranslate("End of game"),<br />
"type" => "manager",<br />
"action" => "stGameEnd",<br />
"args" => "argGameEnd"<br />
)<br />
<br />
);<br />
</pre><br />
<br />
Now, let's create in reversi.game.php the methods that are declared in this game states description file:<br />
* argPlayerTurn<br />
* stNextPlayer<br />
<br />
... and start a new Reversi game.<br />
<br />
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"):<br />
<br />
[[File:reversi7.jpg]]<br />
<br />
== The rules ==<br />
<br />
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:<br />
* As we just said, to help the player to see where she can play.<br />
* When the player plays, to check if she has the right to play here.<br />
<br />
This is pure PHP programming here, and there's 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:<br />
* 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.<br />
* 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.<br />
<br />
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.<br />
<br />
If you want to look into details, please look at the "utility method" sections of reversi.game.php.<br />
<br />
== Display allowed moves ==<br />
<br />
Now, what we want to do is highlight the squares where the player can place a disc.<br />
<br />
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:<br />
<br />
<pre><br />
<br />
function argPlayerTurn()<br />
{<br />
return array(<br />
'possibleMoves' => self::getPossibleMoves( self::getActivePlayerId() )<br />
);<br />
}<br />
</pre><br />
<br />
We are of course using the "getPossibleMoves" method we just developed.<br />
<br />
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:<br />
<br />
<pre><br />
onEnteringState: function( stateName, args )<br />
{<br />
console.log( 'Entering state: '+stateName );<br />
<br />
switch( stateName )<br />
{<br />
case 'playerTurn':<br />
this.updatePossibleMoves( args.args.possibleMoves );<br />
break;<br />
}<br />
},<br />
</pre><br />
<br />
So, when we are entering into "playerTurn" game state, we are calling our "updatePossibleMoves" method. This method looks like this:<br />
<br />
<pre><br />
updatePossibleMoves: function( possibleMoves )<br />
{<br />
// Remove current possible moves<br />
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );<br />
<br />
for( var x in possibleMoves )<br />
{<br />
for( var y in possibleMoves[ x ] )<br />
{<br />
// x,y is a possible move<br />
dojo.addClass( 'square_'+x+'_'+y, 'possibleMove' );<br />
} <br />
}<br />
<br />
this.addTooltipToClass( 'possibleMove', '', _('Place a disc here') );<br />
},<br />
</pre><br />
<br />
The idea here is that we've created a CSS class ("possibleMove") that can be applied to a "square" element to highlight it:<br />
<pre><br />
.possibleMove {<br />
background-color: white;<br />
opacity: 0.2;<br />
filter:alpha(opacity=20); /* For IE8 and earlier */ <br />
cursor: pointer; <br />
}<br />
</pre><br />
<br />
At first, we remove all "possibleMove" classes currently applied with the very useful combination of "dojo.query" and "removeClass" method.<br />
<br />
Then we loop through all possible moves our PHP "updatePossibleMoves" function created for us, and add the "possibleMove" class to each corresponding square.<br />
<br />
Finally, we use the BGA framework "addTooltipToClass" method to associate a tooltip to all those highlighted squares so that players can understand their meaning.<br />
<br />
And here we are:<br />
<br />
[[File:reversi8.jpg.jpg]]<br />
<br />
== Let's play ==<br />
<br />
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:<br />
* When we click on a "possibleMove" square, send the move to the server.<br />
* Server side, check the move is correct, apply Reversi rules and jump to next player.<br />
* Client side, change the disc position to reflect the move.<br />
<br />
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:<br />
<br />
<pre><br />
dojo.query( '.square' ).connect( 'onclick', this, 'onPlayDisc' );<br />
</pre><br />
<br />
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.<br />
<br />
Here's our "onPlayDisc" method below:<br />
<br />
<pre><br />
onPlayDisc: function( evt )<br />
{<br />
// Stop this event propagation<br />
dojo.stopEvent( evt );<br />
<br />
// Get the cliqued square x and y<br />
// Note: square id format is "square_X_Y"<br />
var coords = evt.currentTarget.id.split('_');<br />
var x = coords[1];<br />
var y = coords[2];<br />
<br />
if( ! dojo.hasClass( 'square_'+x+'_'+y, 'possibleMove' ) )<br />
{<br />
// This is not a possible move => the click does nothing<br />
return ;<br />
}<br />
<br />
if( this.checkAction( 'playDisc' ) ) // Check that this action is possible at this moment<br />
{ <br />
this.ajaxcall( "/reversi/reversi/playDisc.html", {<br />
x:x,<br />
y:y<br />
}, this, function( result ) {} );<br />
} <br />
},<br />
</pre><br />
<br />
What we do here is:<br />
* We stop the propagation of the Javascript "onclick" event. Otherwise, it can lead to random behavior so it's always a good idea.<br />
* We get the x/y coordinates of the square by using "evt.currentTarget.id".<br />
* We check that clicked square has the "possibleMove" class, otherwise we know for sure that we can't play there.<br />
* 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.<br />
* Finally, we make a call to the server using BGA "ajaxcall" method with argument x and y.<br />
<br />
Now, we have to manage this "playDisc" action on server side. At first, we introduce a "playDisc" entry point in our "reversi.action.php":<br />
<br />
<pre><br />
public function playDisc()<br />
{<br />
self::setAjaxMode(); <br />
$x = self::getArg( "x", AT_posint, true );<br />
$y = self::getArg( "y", AT_posint, true );<br />
$result = $this->game->playDisc( $x, $y );<br />
self::ajaxResponse( );<br />
}<br />
</pre><br />
<br />
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.<br />
<br />
Now, let's have a look of this playDisc method:<br />
<br />
<pre><br />
function playDisc( $x, $y )<br />
{<br />
// Check that this player is active and that this action is possible at this moment<br />
self::checkAction( 'playDisc' ); <br />
</pre><br />
<br />
... 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).<br />
<br />
<pre><br />
// Now, check if this is a possible move<br />
$board = self::getBoard();<br />
$player_id = self::getActivePlayerId();<br />
$turnedOverDiscs = self::getTurnedOverDiscs( $x, $y, $player_id, $board );<br />
<br />
if( count( $turnedOverDiscs ) > 0 )<br />
{<br />
// This move is possible!<br />
</pre><br />
<br />
...now, we are using the "getTurnedOverDiscs" method again to check that this move is possible.<br />
<br />
<pre><br />
// Let's place a disc at x,y and return all "$returned" discs to the active player<br />
<br />
$sql = "UPDATE board SET board_player='$player_id'<br />
WHERE ( board_x, board_y) IN ( ";<br />
<br />
foreach( $turnedOverDiscs as $turnedOver )<br />
{<br />
$sql .= "('".$turnedOver['x']."','".$turnedOver['y']."'),";<br />
}<br />
$sql .= "('$x','$y') ) ";<br />
<br />
self::DbQuery( $sql );<br />
<br />
</pre><br />
<br />
... we update the database to change the color of all turned over disc + the disc we just placed.<br />
<br />
<pre><br />
// Update scores according to the number of disc on board<br />
$sql = "UPDATE player<br />
SET player_score = (<br />
SELECT COUNT( board_x ) FROM board WHERE board_player=player_id<br />
)";<br />
self::DbQuery( $sql );<br />
<br />
// Statistics<br />
self::incStat( count( $turnedOverDiscs ), "turnedOver", $player_id );<br />
if( ($x==1 && $y==1) || ($x==8 && $y==1) || ($x==1 && $y==8) || ($x==8 && $y==8) )<br />
self::incStat( 1, 'discPlayedOnCorner', $player_id );<br />
else if( $x==1 || $x==8 || $y==1 || $y==8 )<br />
self::incStat( 1, 'discPlayedOnBorder', $player_id );<br />
else if( $x>=3 && $x<=6 && $y>=3 && $y<=6 )<br />
self::incStat( 1, 'discPlayedOnCenter', $player_id );<br />
<br />
</pre><br />
<br />
... now, we update both player score by counting all disc, and we manage game statistics.<br />
<br />
<pre><br />
// Notify<br />
self::notifyAllPlayers( "playDisc", clienttranslate( '${player_name} plays a disc and turns over ${returned_nbr} disc(s)' ), array(<br />
'player_id' => $player_id,<br />
'player_name' => self::getActivePlayerName(),<br />
'returned_nbr' => count( $turnedOverDiscs ),<br />
'x' => $x,<br />
'y' => $y<br />
) );<br />
<br />
self::notifyAllPlayers( "turnOverDiscs", '', array(<br />
'player_id' => $player_id,<br />
'turnedOver' => $turnedOverDiscs<br />
) );<br />
<br />
$newScores = self::getCollectionFromDb( "SELECT player_id, player_score FROM player", true );<br />
self::notifyAllPlayers( "newScores", "", array(<br />
"scores" => $newScores<br />
) );<br />
</pre><br />
<br />
... 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.<br />
<br />
<pre><br />
// Then, go to the next state<br />
$this->gamestate->nextState( 'playDisc' );<br />
}<br />
else<br />
throw new feException( "Impossible move" );<br />
}<br />
</pre><br />
<br />
... 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).<br />
To make the statistics work, we have to initialize them in state.inc.php:<br />
<br />
<pre><br />
// Statistics existing for each player<br />
"player" => array(<br />
<br />
"discPlayedOnCorner" => array( "id"=> 10,<br />
"name" => totranslate("Discs played on a corner"), <br />
"type" => "int" ),<br />
<br />
"discPlayedOnBorder" => array( "id"=> 11,<br />
"name" => totranslate("Discs played on a border"), <br />
"type" => "int" ),<br />
<br />
"discPlayedOnCenter" => array( "id"=> 12,<br />
"name" => totranslate("Discs played on board center part"), <br />
"type" => "int" ),<br />
<br />
"turnedOver" => array( "id"=> 13,<br />
"name" => totranslate("Number of discs turned over"), <br />
"type" => "int" ) <br />
)<br />
</pre><br />
<br />
A last thing to do on the server side is to activate the next player when we enter the "nextPlayer" game state:<br />
<br />
<pre><br />
function stNextPlayer()<br />
{<br />
// Activate next player<br />
$player_id = self::activeNextPlayer();<br />
<br />
self::giveExtraTime( $player_id );<br />
$this->gamestate->nextState( 'nextTurn' );<br />
<br />
}<br />
</pre><br />
<br />
Now, when we play a disc, the rules are checked and the disc appears in the database.<br />
<br />
[[File:reversi9.jpg]]<br />
<br />
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.<br />
<br />
== Make the move appear automatically ==<br />
<br />
Now, what we have to do is process the notifications sent by the server and make the move appear on the interface.<br />
<br />
In our "setupNotifications" method, we register 2 methods for the 2 notifications we created at the previous step ('playDisc' and 'turnOverDiscs'):<br />
<br />
<pre><br />
dojo.subscribe( 'playDisc', this, "notif_playDisc" );<br />
this.notifqueue.setSynchronous( 'playDisc', 500 );<br />
dojo.subscribe( 'turnOverDiscs', this, "notif_turnOverDiscs" );<br />
this.notifqueue.setSynchronous( 'turnOverDiscs', 1500 );<br />
</pre><br />
<br />
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:<br />
* Make a disc slide from the player panel to its place on the board<br />
* (wait 500ms)<br />
* Make all turned over discs blink (and of course turned them over)<br />
* (wait 1500ms)<br />
* Let the next player play.<br />
<br />
Let's have a look now on the "playDisc" notification handler method:<br />
<br />
<pre><br />
notif_playDisc: function( notif )<br />
{<br />
// Remove current possible moves (makes the board more clear)<br />
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' ); <br />
<br />
this.addTokenOnBoard( notif.args.x, notif.args.y, notif.args.player_id );<br />
},<br />
</pre><br />
<br />
No surprise here, we re-used some existing stuff to:<br />
* Remove the highlighted squares.<br />
* Add a new disc on board, coming from player panel.<br />
<br />
Now, here's the method that handles the turnOverDiscs notification:<br />
<br />
<pre><br />
notif_turnOverDiscs: function( notif )<br />
{<br />
// Get the color of the player who is returning the discs<br />
var targetColor = this.gamedatas.players[ notif.args.player_id ].color;<br />
<br />
// Make these discs blink and set them to the specified color<br />
for( var i in notif.args.turnedOver )<br />
{<br />
var token = notif.args.turnedOver[ i ];<br />
<br />
// Make the token blink 2 times<br />
var anim = dojo.fx.chain( [<br />
dojo.fadeOut( { node: 'token_'+token.x+'_'+token.y } ),<br />
dojo.fadeIn( { node: 'token_'+token.x+'_'+token.y } ),<br />
dojo.fadeOut( { <br />
node: 'token_'+token.x+'_'+token.y,<br />
onEnd: function( node ) {<br />
<br />
// Remove any color class<br />
dojo.removeClass( node, [ 'tokencolor_000000', 'tokencolor_ffffff' ] );<br />
// ... and add the good one<br />
dojo.addClass( node, 'tokencolor_'+targetColor );<br />
<br />
} <br />
} ),<br />
dojo.fadeIn( { node: 'token_'+token.x+'_'+token.y } )<br />
<br />
] ); // end of dojo.fx.chain<br />
<br />
// ... and launch the animation<br />
anim.play(); <br />
}<br />
},<br />
</pre><br />
<br />
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].<br />
<br />
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()".</div>Christopheryoderhttp://en.doc.boardgamearena.com/index.php?title=Tutorial_reversi&diff=1365Tutorial reversi2015-02-05T16:49:17Z<p>Christopheryoder: /* The rules */</p>
<hr />
<div><br />
== Introduction ==<br />
<br />
Using this tutorial, you can build a complete working game on the BGA environment: Reversi.<br />
<br />
Before you read this tutorial, you must:<br />
* Read the overall presentations of the BGA Framework ([[Studio|see here]]).<br />
* Know the [http://en.wikipedia.org/wiki/Reversi#Rules rules of Reversi].<br />
* Know the languages used on BGA: PHP, SQL, HTML, CSS, Javascript.<br />
<br />
== Create your first game ==<br />
<br />
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 this 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.<br />
<br />
Thus, you can start a "Reversi" game, and arrive on a void, empty game. Yeah.<br />
<br />
== Let it look like Reversi ==<br />
<br />
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.<br />
<br />
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).<br />
<br />
For Reversi, it's useless to have a 750x750px board - much too big, so we choose this one which fit perfectly (536x528):<br />
<br />
[[File:Board.jpg]]<br />
<br />
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.<br />
<br />
Now, let's make it appears on our game:<br />
* upload board.jpg in your "img/" directory.<br />
* edit "reversi_reversi.tpl" to add a 'div' for your board:<br />
<br />
<pre><br />
<div id="board"><br />
</div><br />
</pre><br />
<br />
* edit your reversi.css file to transform it into a visible board:<br />
<br />
#board {<br />
width: 536px;<br />
height: 528px;<br />
background-image: url('img/board.jpg');<br />
}<br />
<br />
Refresh your page. Here's your board:<br />
<br />
[[File:reversi1.jpg]]<br />
<br />
== Make the squares appears ==<br />
<br />
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. <br />
Obviously, we need 64 squares. To avoid writing 64 'div' elements on our template, we are going to use the "block" feature.<br />
<br />
Let's modify our template like this:<br />
<br />
<pre><br />
<div id="board"><br />
<!-- BEGIN square --><br />
<div id="square_{X}_{Y}" class="square" style="left: {LEFT}px; top: {TOP}px;"></div><br />
<!-- END square --><br />
</div><br />
</pre><br />
<br />
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.<br />
<br />
Let's do it in our "reversi.view.php" file:<br />
<br />
<pre><br />
$this->page->begin_block( "reversi_reversi", "square" );<br />
<br />
$hor_scale = 64.8;<br />
$ver_scale = 64.4;<br />
for( $x=1; $x<=8; $x++ )<br />
{<br />
for( $y=1; $y<=8; $y++ )<br />
{<br />
$this->page->insert_block( "square", array(<br />
'X' => $x,<br />
'Y' => $y,<br />
'LEFT' => round( ($x-1)*$hor_scale+10 ),<br />
'TOP' => round( ($y-1)*$ver_scale+7 )<br />
) );<br />
} <br />
}<br />
</pre><br />
<br />
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.<br />
<br />
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:<br />
<br />
<pre><br />
#board {<br />
width: 536px;<br />
height: 528px;<br />
background-image: url('img/board.jpg');<br />
position: relative;<br />
}<br />
<br />
.square {<br />
width: 62px;<br />
height: 62px;<br />
position: absolute;<br />
background-color: red;<br />
}<br />
</pre><br />
<br />
Explanations:<br />
* With "position: relative" on board, we ensure square elements are positioned relatively to board.<br />
* 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.<br />
<br />
Let's refresh and check our our (beautiful) squares:<br />
<br />
[[File:reversi2.jpg]]<br />
<br />
== The discs ==<br />
<br />
Now, our board is ready to receive some disc tokens!<br />
<br />
At first, we introduce a new 'div' element as a child of "board" to host all these tokens (in our template):<br />
<br />
<pre><br />
<!-- END square --><br />
<br />
<div id="tokens"><br />
</div><br />
</div><br />
</pre><br />
<br />
Then, let's introduce a new piece of art with the discs. We need some transparency here so we are using a png file:<br />
<br />
[[File:tokens.png]]<br />
<br />
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].<br />
<br />
Now, let's separate the disc with some CSS stuff:<br />
<br />
<pre><br />
.token {<br />
width: 56px;<br />
height: 56px;<br />
position: absolute;<br />
background-image: url('img/tokens.png');<br />
}<br />
.tokencolor_ffffff { background-position: 0px 0px; }<br />
.tokencolor_000000 { background-position: -56px 0px; }<br />
</pre><br />
<br />
With this CSS code, we apply the classes "token" and "tokencolor_ffffff" to a div element and we've got a white token. Yeah.<br />
<br />
Note the "position: absolute" which allows us to position tokens on the board and make them "slide" to their positions.<br />
<br />
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".<br />
<br />
In our template file (reversi_reversi.tpl), let's create the piece of HTML needed to display our token:<br />
<br />
<pre><br />
<script type="text/javascript"><br />
<br />
// Templates<br />
<br />
var jstpl_token='<div class="token tokencolor_${color}" id="token_${x_y}"></div>';<br />
<br />
</script><br />
</pre><br />
<br />
Note: we already created the "templates" section for you in the game skeleton.<br />
<br />
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).<br />
<br />
Now, let's create a method in our Javascript code that will make a token appear on the board, using this template:<br />
<br />
<pre><br />
addTokenOnBoard: function( x, y, player )<br />
{<br />
dojo.place( this.format_block( 'jstpl_token', {<br />
x_y: x+'_'+y,<br />
color: this.gamedatas.players[ player ].color<br />
} ) , 'tokens' );<br />
<br />
this.placeOnObject( 'token_'+x+'_'+y, 'overall_player_board_'+player );<br />
this.slideToObject( 'token_'+x+'_'+y, 'square_'+x+'_'+y ).play();<br />
},<br />
</pre><br />
<br />
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.<br />
<br />
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.<br />
<br />
Note: don't forget to call the "play()", otherwise the token remains at its original location.<br />
<br />
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.<br />
<br />
Before we can show a token, we need to set the player colors in the setupNewGame function in reversi.game.php:<br />
<pre><br />
$default_colors = array( "ffffff", "000000" );<br />
</pre><br />
<br />
Now, to test if everything works fine, just call "this.addTokenOnBoard( 2, 2, <your_player_id> )" in your "setup" Javascript method, and reload the page. A token should appear and slide immediately to its position, like this:<br />
<br />
[[File:reversi3.jpg]]<br />
<br />
== The database ==<br />
<br />
We did most of the client-side programming, so let's have a look on the other side now.<br />
<br />
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.<br />
<br />
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.<br />
<br />
[[File:reversi4.jpg]]<br />
<br />
The database model of Reversi is very simple: just one table with the squares of the board. In our dbmodel.sql, we have this:<br />
<br />
<pre><br />
CREATE TABLE IF NOT EXISTS `board` (<br />
`board_x` smallint(5) unsigned NOT NULL,<br />
`board_y` smallint(5) unsigned NOT NULL,<br />
`board_player` int(10) unsigned DEFAULT NULL,<br />
PRIMARY KEY (`board_x`,`board_y`)<br />
) ENGINE=InnoDB;<br />
</pre><br />
<br />
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.<br />
<br />
== Setup the initial game position ==<br />
<br />
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).<br />
<br />
Let's do this:<br />
<br />
<pre><br />
// Init the board<br />
$sql = "INSERT INTO board (board_x,board_y,board_player) VALUES ";<br />
$sql_values = array();<br />
list( $blackplayer_id, $whiteplayer_id ) = array_keys( $players );<br />
for( $x=1; $x<=8; $x++ )<br />
{<br />
for( $y=1; $y<=8; $y++ )<br />
{<br />
$token_value = "NULL";<br />
if( ($x==4 && $y==4) || ($x==5 && $y==5) ) // Initial positions of white player<br />
$token_value = "'$whiteplayer_id'";<br />
else if( ($x==4 && $y==5) || ($x==5 && $y==4) ) // Initial positions of black player<br />
$token_value = "'$blackplayer_id'";<br />
<br />
$sql_values[] = "('$x','$y',$token_value)";<br />
}<br />
}<br />
$sql .= implode( $sql_values, ',' );<br />
self::DbQuery( $sql );<br />
<br />
<br />
// Active first player<br />
self::activeNextPlayer(); <br />
</pre><br />
<br />
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.<br />
<br />
At the end, we call activeNextPlayer to make the first player active at the beginning of the game.<br />
<br />
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):<br />
<br />
<pre><br />
// Get reversi board token<br />
$result['board'] = self::getObjectListFromDB( "SELECT board_x x, board_y y, board_player player<br />
FROM board<br />
WHERE board_player IS NOT NULL" );<br />
</pre><br />
<br />
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.<br />
<br />
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:<br />
<br />
<pre><br />
for( var i in gamedatas.board )<br />
{<br />
var square = gamedatas.board[i];<br />
<br />
if( square.player !== null )<br />
{<br />
this.addTokenOnBoard( square.x, square.y, square.player );<br />
}<br />
}<br />
</pre><br />
<br />
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.<br />
<br />
Reload... and here we are:<br />
<br />
[[File:reversi5.jpg]]<br />
<br />
It starts to smell Reversi here...<br />
<br />
== The game state machine ==<br />
<br />
Now, let's stop our game again, because we are going to start the core game logic.<br />
<br />
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 although. Here's a diagram of our game state machine:<br />
<br />
[[File:reversi6.jpg]]<br />
<br />
And here's our "states.inc.php", according to this diagram:<br />
<br />
<pre><br />
$machinestates = array(<br />
<br />
1 => array(<br />
"name" => "gameSetup",<br />
"description" => clienttranslate("Game setup"),<br />
"type" => "manager",<br />
"action" => "stGameSetup",<br />
"transitions" => array( "" => 10 )<br />
),<br />
<br />
10 => array(<br />
"name" => "playerTurn",<br />
"description" => clienttranslate('${actplayer} must play a disc'),<br />
"descriptionmyturn" => clienttranslate('${you} must play a disc'),<br />
"type" => "activeplayer",<br />
"args" => "argPlayerTurn",<br />
"possibleactions" => array( 'playDisc' ),<br />
"transitions" => array( "playDisc" => 11, "zombiePass" => 11 )<br />
),<br />
<br />
11 => array(<br />
"name" => "nextPlayer",<br />
"type" => "game",<br />
"action" => "stNextPlayer",<br />
"updateGameProgression" => true, <br />
"transitions" => array( "nextTurn" => 10, "cantPlay" => 11, "endGame" => 99 )<br />
),<br />
<br />
99 => array(<br />
"name" => "gameEnd",<br />
"description" => clienttranslate("End of game"),<br />
"type" => "manager",<br />
"action" => "stGameEnd",<br />
"args" => "argGameEnd"<br />
)<br />
<br />
);<br />
</pre><br />
<br />
Now, let's create in reversi.game.php the methods that are declared in this game states description file:<br />
* argPlayerTurn<br />
* stNextPlayer<br />
<br />
... and start a new Reversi game.<br />
<br />
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"):<br />
<br />
[[File:reversi7.jpg]]<br />
<br />
== The rules ==<br />
<br />
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:<br />
* As we just said, to help the player to see where she can play.<br />
* When the player play, to check if she has the right to play here.<br />
<br />
This is pure PHP programming here, and there's 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:<br />
* 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.<br />
* 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.<br />
<br />
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.<br />
<br />
If you want to look into details, please look at the "utility method" sections of reversi.game.php.<br />
<br />
== Display allowed moves ==<br />
<br />
Now, what we want to do is highlight the squares where the player can place a disc.<br />
<br />
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:<br />
<br />
<pre><br />
<br />
function argPlayerTurn()<br />
{<br />
return array(<br />
'possibleMoves' => self::getPossibleMoves( self::getActivePlayerId() )<br />
);<br />
}<br />
</pre><br />
<br />
We are of course using the "getPossibleMoves" method we just developed.<br />
<br />
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:<br />
<br />
<pre><br />
onEnteringState: function( stateName, args )<br />
{<br />
console.log( 'Entering state: '+stateName );<br />
<br />
switch( stateName )<br />
{<br />
case 'playerTurn':<br />
this.updatePossibleMoves( args.args.possibleMoves );<br />
break;<br />
}<br />
},<br />
</pre><br />
<br />
So, when we are entering into "playerTurn" game state, we are calling our "updatePossibleMoves" method. This method looks like this:<br />
<br />
<pre><br />
updatePossibleMoves: function( possibleMoves )<br />
{<br />
// Remove current possible moves<br />
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );<br />
<br />
for( var x in possibleMoves )<br />
{<br />
for( var y in possibleMoves[ x ] )<br />
{<br />
// x,y is a possible move<br />
dojo.addClass( 'square_'+x+'_'+y, 'possibleMove' );<br />
} <br />
}<br />
<br />
this.addTooltipToClass( 'possibleMove', '', _('Place a disc here') );<br />
},<br />
</pre><br />
<br />
The idea here is that we've created a CSS class ("possibleMove") that can be applied to a "square" element to highlight it:<br />
<pre><br />
.possibleMove {<br />
background-color: white;<br />
opacity: 0.2;<br />
filter:alpha(opacity=20); /* For IE8 and earlier */ <br />
cursor: pointer; <br />
}<br />
</pre><br />
<br />
At first, we remove all "possibleMove" classes currently applied with the very useful combination of "dojo.query" and "removeClass" method.<br />
<br />
Then we loop through all possible moves our PHP "updatePossibleMoves" function created for us, and add the "possibleMove" class to each corresponding square.<br />
<br />
Finally, we use the BGA framework "addTooltipToClass" method to associate a tooltip to all those highlighted squares so that players can understand their meaning.<br />
<br />
And here we are:<br />
<br />
[[File:reversi8.jpg.jpg]]<br />
<br />
== Let's play ==<br />
<br />
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:<br />
* When we click on a "possibleMove" square, send the move to the server.<br />
* Server side, check the move is correct, apply Reversi rules and jump to next player.<br />
* Client side, change the disc position to reflect the move.<br />
<br />
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:<br />
<br />
<pre><br />
dojo.query( '.square' ).connect( 'onclick', this, 'onPlayDisc' );<br />
</pre><br />
<br />
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.<br />
<br />
Here's our "onPlayDisc" method below:<br />
<br />
<pre><br />
onPlayDisc: function( evt )<br />
{<br />
// Stop this event propagation<br />
dojo.stopEvent( evt );<br />
<br />
// Get the cliqued square x and y<br />
// Note: square id format is "square_X_Y"<br />
var coords = evt.currentTarget.id.split('_');<br />
var x = coords[1];<br />
var y = coords[2];<br />
<br />
if( ! dojo.hasClass( 'square_'+x+'_'+y, 'possibleMove' ) )<br />
{<br />
// This is not a possible move => the click does nothing<br />
return ;<br />
}<br />
<br />
if( this.checkAction( 'playDisc' ) ) // Check that this action is possible at this moment<br />
{ <br />
this.ajaxcall( "/reversi/reversi/playDisc.html", {<br />
x:x,<br />
y:y<br />
}, this, function( result ) {} );<br />
} <br />
},<br />
</pre><br />
<br />
What we do here is:<br />
* We stop the propagation of the Javascript "onclick" event. Otherwise, it can lead to random behavior so it's always a good idea.<br />
* We get the x/y coordinates of the square by using "evt.currentTarget.id".<br />
* We check that clicked square has the "possibleMove" class, otherwise we know for sure that we can't play there.<br />
* 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.<br />
* Finally, we make a call to the server using BGA "ajaxcall" method with argument x and y.<br />
<br />
Now, we have to manage this "playDisc" action on server side. At first, we introduce a "playDisc" entry point in our "reversi.action.php":<br />
<br />
<pre><br />
public function playDisc()<br />
{<br />
self::setAjaxMode(); <br />
$x = self::getArg( "x", AT_posint, true );<br />
$y = self::getArg( "y", AT_posint, true );<br />
$result = $this->game->playDisc( $x, $y );<br />
self::ajaxResponse( );<br />
}<br />
</pre><br />
<br />
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.<br />
<br />
Now, let's have a look of this playDisc method:<br />
<br />
<pre><br />
function playDisc( $x, $y )<br />
{<br />
// Check that this player is active and that this action is possible at this moment<br />
self::checkAction( 'playDisc' ); <br />
</pre><br />
<br />
... 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).<br />
<br />
<pre><br />
// Now, check if this is a possible move<br />
$board = self::getBoard();<br />
$player_id = self::getActivePlayerId();<br />
$turnedOverDiscs = self::getTurnedOverDiscs( $x, $y, $player_id, $board );<br />
<br />
if( count( $turnedOverDiscs ) > 0 )<br />
{<br />
// This move is possible!<br />
</pre><br />
<br />
...now, we are using the "getTurnedOverDiscs" method again to check that this move is possible.<br />
<br />
<pre><br />
// Let's place a disc at x,y and return all "$returned" discs to the active player<br />
<br />
$sql = "UPDATE board SET board_player='$player_id'<br />
WHERE ( board_x, board_y) IN ( ";<br />
<br />
foreach( $turnedOverDiscs as $turnedOver )<br />
{<br />
$sql .= "('".$turnedOver['x']."','".$turnedOver['y']."'),";<br />
}<br />
$sql .= "('$x','$y') ) ";<br />
<br />
self::DbQuery( $sql );<br />
<br />
</pre><br />
<br />
... we update the database to change the color of all turned over disc + the disc we just placed.<br />
<br />
<pre><br />
// Update scores according to the number of disc on board<br />
$sql = "UPDATE player<br />
SET player_score = (<br />
SELECT COUNT( board_x ) FROM board WHERE board_player=player_id<br />
)";<br />
self::DbQuery( $sql );<br />
<br />
// Statistics<br />
self::incStat( count( $turnedOverDiscs ), "turnedOver", $player_id );<br />
if( ($x==1 && $y==1) || ($x==8 && $y==1) || ($x==1 && $y==8) || ($x==8 && $y==8) )<br />
self::incStat( 1, 'discPlayedOnCorner', $player_id );<br />
else if( $x==1 || $x==8 || $y==1 || $y==8 )<br />
self::incStat( 1, 'discPlayedOnBorder', $player_id );<br />
else if( $x>=3 && $x<=6 && $y>=3 && $y<=6 )<br />
self::incStat( 1, 'discPlayedOnCenter', $player_id );<br />
<br />
</pre><br />
<br />
... now, we update both player score by counting all disc, and we manage game statistics.<br />
<br />
<pre><br />
// Notify<br />
self::notifyAllPlayers( "playDisc", clienttranslate( '${player_name} plays a disc and turns over ${returned_nbr} disc(s)' ), array(<br />
'player_id' => $player_id,<br />
'player_name' => self::getActivePlayerName(),<br />
'returned_nbr' => count( $turnedOverDiscs ),<br />
'x' => $x,<br />
'y' => $y<br />
) );<br />
<br />
self::notifyAllPlayers( "turnOverDiscs", '', array(<br />
'player_id' => $player_id,<br />
'turnedOver' => $turnedOverDiscs<br />
) );<br />
<br />
$newScores = self::getCollectionFromDb( "SELECT player_id, player_score FROM player", true );<br />
self::notifyAllPlayers( "newScores", "", array(<br />
"scores" => $newScores<br />
) );<br />
</pre><br />
<br />
... 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.<br />
<br />
<pre><br />
// Then, go to the next state<br />
$this->gamestate->nextState( 'playDisc' );<br />
}<br />
else<br />
throw new feException( "Impossible move" );<br />
}<br />
</pre><br />
<br />
... 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).<br />
To make the statistics work, we have to initialize them in state.inc.php:<br />
<br />
<pre><br />
// Statistics existing for each player<br />
"player" => array(<br />
<br />
"discPlayedOnCorner" => array( "id"=> 10,<br />
"name" => totranslate("Discs played on a corner"), <br />
"type" => "int" ),<br />
<br />
"discPlayedOnBorder" => array( "id"=> 11,<br />
"name" => totranslate("Discs played on a border"), <br />
"type" => "int" ),<br />
<br />
"discPlayedOnCenter" => array( "id"=> 12,<br />
"name" => totranslate("Discs played on board center part"), <br />
"type" => "int" ),<br />
<br />
"turnedOver" => array( "id"=> 13,<br />
"name" => totranslate("Number of discs turned over"), <br />
"type" => "int" ) <br />
)<br />
</pre><br />
<br />
A last thing to do on the server side is to activate the next player when we enter the "nextPlayer" game state:<br />
<br />
<pre><br />
function stNextPlayer()<br />
{<br />
// Activate next player<br />
$player_id = self::activeNextPlayer();<br />
<br />
self::giveExtraTime( $player_id );<br />
$this->gamestate->nextState( 'nextTurn' );<br />
<br />
}<br />
</pre><br />
<br />
Now, when we play a disc, the rules are checked and the disc appears in the database.<br />
<br />
[[File:reversi9.jpg]]<br />
<br />
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.<br />
<br />
== Make the move appear automatically ==<br />
<br />
Now, what we have to do is process the notifications sent by the server and make the move appear on the interface.<br />
<br />
In our "setupNotifications" method, we register 2 methods for the 2 notifications we created at the previous step ('playDisc' and 'turnOverDiscs'):<br />
<br />
<pre><br />
dojo.subscribe( 'playDisc', this, "notif_playDisc" );<br />
this.notifqueue.setSynchronous( 'playDisc', 500 );<br />
dojo.subscribe( 'turnOverDiscs', this, "notif_turnOverDiscs" );<br />
this.notifqueue.setSynchronous( 'turnOverDiscs', 1500 );<br />
</pre><br />
<br />
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:<br />
* Make a disc slide from the player panel to its place on the board<br />
* (wait 500ms)<br />
* Make all turned over discs blink (and of course turned them over)<br />
* (wait 1500ms)<br />
* Let the next player play.<br />
<br />
Let's have a look now on the "playDisc" notification handler method:<br />
<br />
<pre><br />
notif_playDisc: function( notif )<br />
{<br />
// Remove current possible moves (makes the board more clear)<br />
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' ); <br />
<br />
this.addTokenOnBoard( notif.args.x, notif.args.y, notif.args.player_id );<br />
},<br />
</pre><br />
<br />
No surprise here, we re-used some existing stuff to:<br />
* Remove the highlighted squares.<br />
* Add a new disc on board, coming from player panel.<br />
<br />
Now, here's the method that handles the turnOverDiscs notification:<br />
<br />
<pre><br />
notif_turnOverDiscs: function( notif )<br />
{<br />
// Get the color of the player who is returning the discs<br />
var targetColor = this.gamedatas.players[ notif.args.player_id ].color;<br />
<br />
// Make these discs blink and set them to the specified color<br />
for( var i in notif.args.turnedOver )<br />
{<br />
var token = notif.args.turnedOver[ i ];<br />
<br />
// Make the token blink 2 times<br />
var anim = dojo.fx.chain( [<br />
dojo.fadeOut( { node: 'token_'+token.x+'_'+token.y } ),<br />
dojo.fadeIn( { node: 'token_'+token.x+'_'+token.y } ),<br />
dojo.fadeOut( { <br />
node: 'token_'+token.x+'_'+token.y,<br />
onEnd: function( node ) {<br />
<br />
// Remove any color class<br />
dojo.removeClass( node, [ 'tokencolor_000000', 'tokencolor_ffffff' ] );<br />
// ... and add the good one<br />
dojo.addClass( node, 'tokencolor_'+targetColor );<br />
<br />
} <br />
} ),<br />
dojo.fadeIn( { node: 'token_'+token.x+'_'+token.y } )<br />
<br />
] ); // end of dojo.fx.chain<br />
<br />
// ... and launch the animation<br />
anim.play(); <br />
}<br />
},<br />
</pre><br />
<br />
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].<br />
<br />
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()".</div>Christopheryoderhttp://en.doc.boardgamearena.com/index.php?title=Tutorial_reversi&diff=1364Tutorial reversi2015-02-05T16:47:43Z<p>Christopheryoder: /* Display allowed moves */</p>
<hr />
<div><br />
== Introduction ==<br />
<br />
Using this tutorial, you can build a complete working game on the BGA environment: Reversi.<br />
<br />
Before you read this tutorial, you must:<br />
* Read the overall presentations of the BGA Framework ([[Studio|see here]]).<br />
* Know the [http://en.wikipedia.org/wiki/Reversi#Rules rules of Reversi].<br />
* Know the languages used on BGA: PHP, SQL, HTML, CSS, Javascript.<br />
<br />
== Create your first game ==<br />
<br />
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 this 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.<br />
<br />
Thus, you can start a "Reversi" game, and arrive on a void, empty game. Yeah.<br />
<br />
== Let it look like Reversi ==<br />
<br />
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.<br />
<br />
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).<br />
<br />
For Reversi, it's useless to have a 750x750px board - much too big, so we choose this one which fit perfectly (536x528):<br />
<br />
[[File:Board.jpg]]<br />
<br />
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.<br />
<br />
Now, let's make it appears on our game:<br />
* upload board.jpg in your "img/" directory.<br />
* edit "reversi_reversi.tpl" to add a 'div' for your board:<br />
<br />
<pre><br />
<div id="board"><br />
</div><br />
</pre><br />
<br />
* edit your reversi.css file to transform it into a visible board:<br />
<br />
#board {<br />
width: 536px;<br />
height: 528px;<br />
background-image: url('img/board.jpg');<br />
}<br />
<br />
Refresh your page. Here's your board:<br />
<br />
[[File:reversi1.jpg]]<br />
<br />
== Make the squares appears ==<br />
<br />
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. <br />
Obviously, we need 64 squares. To avoid writing 64 'div' elements on our template, we are going to use the "block" feature.<br />
<br />
Let's modify our template like this:<br />
<br />
<pre><br />
<div id="board"><br />
<!-- BEGIN square --><br />
<div id="square_{X}_{Y}" class="square" style="left: {LEFT}px; top: {TOP}px;"></div><br />
<!-- END square --><br />
</div><br />
</pre><br />
<br />
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.<br />
<br />
Let's do it in our "reversi.view.php" file:<br />
<br />
<pre><br />
$this->page->begin_block( "reversi_reversi", "square" );<br />
<br />
$hor_scale = 64.8;<br />
$ver_scale = 64.4;<br />
for( $x=1; $x<=8; $x++ )<br />
{<br />
for( $y=1; $y<=8; $y++ )<br />
{<br />
$this->page->insert_block( "square", array(<br />
'X' => $x,<br />
'Y' => $y,<br />
'LEFT' => round( ($x-1)*$hor_scale+10 ),<br />
'TOP' => round( ($y-1)*$ver_scale+7 )<br />
) );<br />
} <br />
}<br />
</pre><br />
<br />
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.<br />
<br />
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:<br />
<br />
<pre><br />
#board {<br />
width: 536px;<br />
height: 528px;<br />
background-image: url('img/board.jpg');<br />
position: relative;<br />
}<br />
<br />
.square {<br />
width: 62px;<br />
height: 62px;<br />
position: absolute;<br />
background-color: red;<br />
}<br />
</pre><br />
<br />
Explanations:<br />
* With "position: relative" on board, we ensure square elements are positioned relatively to board.<br />
* 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.<br />
<br />
Let's refresh and check our our (beautiful) squares:<br />
<br />
[[File:reversi2.jpg]]<br />
<br />
== The discs ==<br />
<br />
Now, our board is ready to receive some disc tokens!<br />
<br />
At first, we introduce a new 'div' element as a child of "board" to host all these tokens (in our template):<br />
<br />
<pre><br />
<!-- END square --><br />
<br />
<div id="tokens"><br />
</div><br />
</div><br />
</pre><br />
<br />
Then, let's introduce a new piece of art with the discs. We need some transparency here so we are using a png file:<br />
<br />
[[File:tokens.png]]<br />
<br />
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].<br />
<br />
Now, let's separate the disc with some CSS stuff:<br />
<br />
<pre><br />
.token {<br />
width: 56px;<br />
height: 56px;<br />
position: absolute;<br />
background-image: url('img/tokens.png');<br />
}<br />
.tokencolor_ffffff { background-position: 0px 0px; }<br />
.tokencolor_000000 { background-position: -56px 0px; }<br />
</pre><br />
<br />
With this CSS code, we apply the classes "token" and "tokencolor_ffffff" to a div element and we've got a white token. Yeah.<br />
<br />
Note the "position: absolute" which allows us to position tokens on the board and make them "slide" to their positions.<br />
<br />
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".<br />
<br />
In our template file (reversi_reversi.tpl), let's create the piece of HTML needed to display our token:<br />
<br />
<pre><br />
<script type="text/javascript"><br />
<br />
// Templates<br />
<br />
var jstpl_token='<div class="token tokencolor_${color}" id="token_${x_y}"></div>';<br />
<br />
</script><br />
</pre><br />
<br />
Note: we already created the "templates" section for you in the game skeleton.<br />
<br />
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).<br />
<br />
Now, let's create a method in our Javascript code that will make a token appear on the board, using this template:<br />
<br />
<pre><br />
addTokenOnBoard: function( x, y, player )<br />
{<br />
dojo.place( this.format_block( 'jstpl_token', {<br />
x_y: x+'_'+y,<br />
color: this.gamedatas.players[ player ].color<br />
} ) , 'tokens' );<br />
<br />
this.placeOnObject( 'token_'+x+'_'+y, 'overall_player_board_'+player );<br />
this.slideToObject( 'token_'+x+'_'+y, 'square_'+x+'_'+y ).play();<br />
},<br />
</pre><br />
<br />
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.<br />
<br />
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.<br />
<br />
Note: don't forget to call the "play()", otherwise the token remains at its original location.<br />
<br />
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.<br />
<br />
Before we can show a token, we need to set the player colors in the setupNewGame function in reversi.game.php:<br />
<pre><br />
$default_colors = array( "ffffff", "000000" );<br />
</pre><br />
<br />
Now, to test if everything works fine, just call "this.addTokenOnBoard( 2, 2, <your_player_id> )" in your "setup" Javascript method, and reload the page. A token should appear and slide immediately to its position, like this:<br />
<br />
[[File:reversi3.jpg]]<br />
<br />
== The database ==<br />
<br />
We did most of the client-side programming, so let's have a look on the other side now.<br />
<br />
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.<br />
<br />
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.<br />
<br />
[[File:reversi4.jpg]]<br />
<br />
The database model of Reversi is very simple: just one table with the squares of the board. In our dbmodel.sql, we have this:<br />
<br />
<pre><br />
CREATE TABLE IF NOT EXISTS `board` (<br />
`board_x` smallint(5) unsigned NOT NULL,<br />
`board_y` smallint(5) unsigned NOT NULL,<br />
`board_player` int(10) unsigned DEFAULT NULL,<br />
PRIMARY KEY (`board_x`,`board_y`)<br />
) ENGINE=InnoDB;<br />
</pre><br />
<br />
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.<br />
<br />
== Setup the initial game position ==<br />
<br />
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).<br />
<br />
Let's do this:<br />
<br />
<pre><br />
// Init the board<br />
$sql = "INSERT INTO board (board_x,board_y,board_player) VALUES ";<br />
$sql_values = array();<br />
list( $blackplayer_id, $whiteplayer_id ) = array_keys( $players );<br />
for( $x=1; $x<=8; $x++ )<br />
{<br />
for( $y=1; $y<=8; $y++ )<br />
{<br />
$token_value = "NULL";<br />
if( ($x==4 && $y==4) || ($x==5 && $y==5) ) // Initial positions of white player<br />
$token_value = "'$whiteplayer_id'";<br />
else if( ($x==4 && $y==5) || ($x==5 && $y==4) ) // Initial positions of black player<br />
$token_value = "'$blackplayer_id'";<br />
<br />
$sql_values[] = "('$x','$y',$token_value)";<br />
}<br />
}<br />
$sql .= implode( $sql_values, ',' );<br />
self::DbQuery( $sql );<br />
<br />
<br />
// Active first player<br />
self::activeNextPlayer(); <br />
</pre><br />
<br />
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.<br />
<br />
At the end, we call activeNextPlayer to make the first player active at the beginning of the game.<br />
<br />
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):<br />
<br />
<pre><br />
// Get reversi board token<br />
$result['board'] = self::getObjectListFromDB( "SELECT board_x x, board_y y, board_player player<br />
FROM board<br />
WHERE board_player IS NOT NULL" );<br />
</pre><br />
<br />
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.<br />
<br />
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:<br />
<br />
<pre><br />
for( var i in gamedatas.board )<br />
{<br />
var square = gamedatas.board[i];<br />
<br />
if( square.player !== null )<br />
{<br />
this.addTokenOnBoard( square.x, square.y, square.player );<br />
}<br />
}<br />
</pre><br />
<br />
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.<br />
<br />
Reload... and here we are:<br />
<br />
[[File:reversi5.jpg]]<br />
<br />
It starts to smell Reversi here...<br />
<br />
== The game state machine ==<br />
<br />
Now, let's stop our game again, because we are going to start the core game logic.<br />
<br />
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 although. Here's a diagram of our game state machine:<br />
<br />
[[File:reversi6.jpg]]<br />
<br />
And here's our "states.inc.php", according to this diagram:<br />
<br />
<pre><br />
$machinestates = array(<br />
<br />
1 => array(<br />
"name" => "gameSetup",<br />
"description" => clienttranslate("Game setup"),<br />
"type" => "manager",<br />
"action" => "stGameSetup",<br />
"transitions" => array( "" => 10 )<br />
),<br />
<br />
10 => array(<br />
"name" => "playerTurn",<br />
"description" => clienttranslate('${actplayer} must play a disc'),<br />
"descriptionmyturn" => clienttranslate('${you} must play a disc'),<br />
"type" => "activeplayer",<br />
"args" => "argPlayerTurn",<br />
"possibleactions" => array( 'playDisc' ),<br />
"transitions" => array( "playDisc" => 11, "zombiePass" => 11 )<br />
),<br />
<br />
11 => array(<br />
"name" => "nextPlayer",<br />
"type" => "game",<br />
"action" => "stNextPlayer",<br />
"updateGameProgression" => true, <br />
"transitions" => array( "nextTurn" => 10, "cantPlay" => 11, "endGame" => 99 )<br />
),<br />
<br />
99 => array(<br />
"name" => "gameEnd",<br />
"description" => clienttranslate("End of game"),<br />
"type" => "manager",<br />
"action" => "stGameEnd",<br />
"args" => "argGameEnd"<br />
)<br />
<br />
);<br />
</pre><br />
<br />
Now, let's create in reversi.game.php the methods that are declared in this game states description file:<br />
* argPlayerTurn<br />
* stNextPlayer<br />
<br />
... and start a new Reversi game.<br />
<br />
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"):<br />
<br />
[[File:reversi7.jpg]]<br />
<br />
== The rules ==<br />
<br />
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:<br />
* As we just said, to help the player to see where he can play.<br />
* When the player play, to check if he has the right to play here.<br />
<br />
This is pure PHP programming here, and there's 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:<br />
* 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.<br />
* 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.<br />
<br />
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.<br />
<br />
If you want to look into details, please look at the "utility method" sections of reversi.game.php.<br />
<br />
== Display allowed moves ==<br />
<br />
Now, what we want to do is highlight the squares where the player can place a disc.<br />
<br />
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:<br />
<br />
<pre><br />
<br />
function argPlayerTurn()<br />
{<br />
return array(<br />
'possibleMoves' => self::getPossibleMoves( self::getActivePlayerId() )<br />
);<br />
}<br />
</pre><br />
<br />
We are of course using the "getPossibleMoves" method we just developed.<br />
<br />
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:<br />
<br />
<pre><br />
onEnteringState: function( stateName, args )<br />
{<br />
console.log( 'Entering state: '+stateName );<br />
<br />
switch( stateName )<br />
{<br />
case 'playerTurn':<br />
this.updatePossibleMoves( args.args.possibleMoves );<br />
break;<br />
}<br />
},<br />
</pre><br />
<br />
So, when we are entering into "playerTurn" game state, we are calling our "updatePossibleMoves" method. This method looks like this:<br />
<br />
<pre><br />
updatePossibleMoves: function( possibleMoves )<br />
{<br />
// Remove current possible moves<br />
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );<br />
<br />
for( var x in possibleMoves )<br />
{<br />
for( var y in possibleMoves[ x ] )<br />
{<br />
// x,y is a possible move<br />
dojo.addClass( 'square_'+x+'_'+y, 'possibleMove' );<br />
} <br />
}<br />
<br />
this.addTooltipToClass( 'possibleMove', '', _('Place a disc here') );<br />
},<br />
</pre><br />
<br />
The idea here is that we've created a CSS class ("possibleMove") that can be applied to a "square" element to highlight it:<br />
<pre><br />
.possibleMove {<br />
background-color: white;<br />
opacity: 0.2;<br />
filter:alpha(opacity=20); /* For IE8 and earlier */ <br />
cursor: pointer; <br />
}<br />
</pre><br />
<br />
At first, we remove all "possibleMove" classes currently applied with the very useful combination of "dojo.query" and "removeClass" method.<br />
<br />
Then we loop through all possible moves our PHP "updatePossibleMoves" function created for us, and add the "possibleMove" class to each corresponding square.<br />
<br />
Finally, we use the BGA framework "addTooltipToClass" method to associate a tooltip to all those highlighted squares so that players can understand their meaning.<br />
<br />
And here we are:<br />
<br />
[[File:reversi8.jpg.jpg]]<br />
<br />
== Let's play ==<br />
<br />
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:<br />
* When we click on a "possibleMove" square, send the move to the server.<br />
* Server side, check the move is correct, apply Reversi rules and jump to next player.<br />
* Client side, change the disc position to reflect the move.<br />
<br />
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:<br />
<br />
<pre><br />
dojo.query( '.square' ).connect( 'onclick', this, 'onPlayDisc' );<br />
</pre><br />
<br />
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.<br />
<br />
Here's our "onPlayDisc" method below:<br />
<br />
<pre><br />
onPlayDisc: function( evt )<br />
{<br />
// Stop this event propagation<br />
dojo.stopEvent( evt );<br />
<br />
// Get the cliqued square x and y<br />
// Note: square id format is "square_X_Y"<br />
var coords = evt.currentTarget.id.split('_');<br />
var x = coords[1];<br />
var y = coords[2];<br />
<br />
if( ! dojo.hasClass( 'square_'+x+'_'+y, 'possibleMove' ) )<br />
{<br />
// This is not a possible move => the click does nothing<br />
return ;<br />
}<br />
<br />
if( this.checkAction( 'playDisc' ) ) // Check that this action is possible at this moment<br />
{ <br />
this.ajaxcall( "/reversi/reversi/playDisc.html", {<br />
x:x,<br />
y:y<br />
}, this, function( result ) {} );<br />
} <br />
},<br />
</pre><br />
<br />
What we do here is:<br />
* We stop the propagation of the Javascript "onclick" event. Otherwise, it can lead to random behavior so it's always a good idea.<br />
* We get the x/y coordinates of the square by using "evt.currentTarget.id".<br />
* We check that clicked square has the "possibleMove" class, otherwise we know for sure that we can't play there.<br />
* 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.<br />
* Finally, we make a call to the server using BGA "ajaxcall" method with argument x and y.<br />
<br />
Now, we have to manage this "playDisc" action on server side. At first, we introduce a "playDisc" entry point in our "reversi.action.php":<br />
<br />
<pre><br />
public function playDisc()<br />
{<br />
self::setAjaxMode(); <br />
$x = self::getArg( "x", AT_posint, true );<br />
$y = self::getArg( "y", AT_posint, true );<br />
$result = $this->game->playDisc( $x, $y );<br />
self::ajaxResponse( );<br />
}<br />
</pre><br />
<br />
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.<br />
<br />
Now, let's have a look of this playDisc method:<br />
<br />
<pre><br />
function playDisc( $x, $y )<br />
{<br />
// Check that this player is active and that this action is possible at this moment<br />
self::checkAction( 'playDisc' ); <br />
</pre><br />
<br />
... 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).<br />
<br />
<pre><br />
// Now, check if this is a possible move<br />
$board = self::getBoard();<br />
$player_id = self::getActivePlayerId();<br />
$turnedOverDiscs = self::getTurnedOverDiscs( $x, $y, $player_id, $board );<br />
<br />
if( count( $turnedOverDiscs ) > 0 )<br />
{<br />
// This move is possible!<br />
</pre><br />
<br />
...now, we are using the "getTurnedOverDiscs" method again to check that this move is possible.<br />
<br />
<pre><br />
// Let's place a disc at x,y and return all "$returned" discs to the active player<br />
<br />
$sql = "UPDATE board SET board_player='$player_id'<br />
WHERE ( board_x, board_y) IN ( ";<br />
<br />
foreach( $turnedOverDiscs as $turnedOver )<br />
{<br />
$sql .= "('".$turnedOver['x']."','".$turnedOver['y']."'),";<br />
}<br />
$sql .= "('$x','$y') ) ";<br />
<br />
self::DbQuery( $sql );<br />
<br />
</pre><br />
<br />
... we update the database to change the color of all turned over disc + the disc we just placed.<br />
<br />
<pre><br />
// Update scores according to the number of disc on board<br />
$sql = "UPDATE player<br />
SET player_score = (<br />
SELECT COUNT( board_x ) FROM board WHERE board_player=player_id<br />
)";<br />
self::DbQuery( $sql );<br />
<br />
// Statistics<br />
self::incStat( count( $turnedOverDiscs ), "turnedOver", $player_id );<br />
if( ($x==1 && $y==1) || ($x==8 && $y==1) || ($x==1 && $y==8) || ($x==8 && $y==8) )<br />
self::incStat( 1, 'discPlayedOnCorner', $player_id );<br />
else if( $x==1 || $x==8 || $y==1 || $y==8 )<br />
self::incStat( 1, 'discPlayedOnBorder', $player_id );<br />
else if( $x>=3 && $x<=6 && $y>=3 && $y<=6 )<br />
self::incStat( 1, 'discPlayedOnCenter', $player_id );<br />
<br />
</pre><br />
<br />
... now, we update both player score by counting all disc, and we manage game statistics.<br />
<br />
<pre><br />
// Notify<br />
self::notifyAllPlayers( "playDisc", clienttranslate( '${player_name} plays a disc and turns over ${returned_nbr} disc(s)' ), array(<br />
'player_id' => $player_id,<br />
'player_name' => self::getActivePlayerName(),<br />
'returned_nbr' => count( $turnedOverDiscs ),<br />
'x' => $x,<br />
'y' => $y<br />
) );<br />
<br />
self::notifyAllPlayers( "turnOverDiscs", '', array(<br />
'player_id' => $player_id,<br />
'turnedOver' => $turnedOverDiscs<br />
) );<br />
<br />
$newScores = self::getCollectionFromDb( "SELECT player_id, player_score FROM player", true );<br />
self::notifyAllPlayers( "newScores", "", array(<br />
"scores" => $newScores<br />
) );<br />
</pre><br />
<br />
... 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.<br />
<br />
<pre><br />
// Then, go to the next state<br />
$this->gamestate->nextState( 'playDisc' );<br />
}<br />
else<br />
throw new feException( "Impossible move" );<br />
}<br />
</pre><br />
<br />
... 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).<br />
To make the statistics work, we have to initialize them in state.inc.php:<br />
<br />
<pre><br />
// Statistics existing for each player<br />
"player" => array(<br />
<br />
"discPlayedOnCorner" => array( "id"=> 10,<br />
"name" => totranslate("Discs played on a corner"), <br />
"type" => "int" ),<br />
<br />
"discPlayedOnBorder" => array( "id"=> 11,<br />
"name" => totranslate("Discs played on a border"), <br />
"type" => "int" ),<br />
<br />
"discPlayedOnCenter" => array( "id"=> 12,<br />
"name" => totranslate("Discs played on board center part"), <br />
"type" => "int" ),<br />
<br />
"turnedOver" => array( "id"=> 13,<br />
"name" => totranslate("Number of discs turned over"), <br />
"type" => "int" ) <br />
)<br />
</pre><br />
<br />
A last thing to do on the server side is to activate the next player when we enter the "nextPlayer" game state:<br />
<br />
<pre><br />
function stNextPlayer()<br />
{<br />
// Activate next player<br />
$player_id = self::activeNextPlayer();<br />
<br />
self::giveExtraTime( $player_id );<br />
$this->gamestate->nextState( 'nextTurn' );<br />
<br />
}<br />
</pre><br />
<br />
Now, when we play a disc, the rules are checked and the disc appears in the database.<br />
<br />
[[File:reversi9.jpg]]<br />
<br />
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.<br />
<br />
== Make the move appear automatically ==<br />
<br />
Now, what we have to do is process the notifications sent by the server and make the move appear on the interface.<br />
<br />
In our "setupNotifications" method, we register 2 methods for the 2 notifications we created at the previous step ('playDisc' and 'turnOverDiscs'):<br />
<br />
<pre><br />
dojo.subscribe( 'playDisc', this, "notif_playDisc" );<br />
this.notifqueue.setSynchronous( 'playDisc', 500 );<br />
dojo.subscribe( 'turnOverDiscs', this, "notif_turnOverDiscs" );<br />
this.notifqueue.setSynchronous( 'turnOverDiscs', 1500 );<br />
</pre><br />
<br />
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:<br />
* Make a disc slide from the player panel to its place on the board<br />
* (wait 500ms)<br />
* Make all turned over discs blink (and of course turned them over)<br />
* (wait 1500ms)<br />
* Let the next player play.<br />
<br />
Let's have a look now on the "playDisc" notification handler method:<br />
<br />
<pre><br />
notif_playDisc: function( notif )<br />
{<br />
// Remove current possible moves (makes the board more clear)<br />
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' ); <br />
<br />
this.addTokenOnBoard( notif.args.x, notif.args.y, notif.args.player_id );<br />
},<br />
</pre><br />
<br />
No surprise here, we re-used some existing stuff to:<br />
* Remove the highlighted squares.<br />
* Add a new disc on board, coming from player panel.<br />
<br />
Now, here's the method that handles the turnOverDiscs notification:<br />
<br />
<pre><br />
notif_turnOverDiscs: function( notif )<br />
{<br />
// Get the color of the player who is returning the discs<br />
var targetColor = this.gamedatas.players[ notif.args.player_id ].color;<br />
<br />
// Make these discs blink and set them to the specified color<br />
for( var i in notif.args.turnedOver )<br />
{<br />
var token = notif.args.turnedOver[ i ];<br />
<br />
// Make the token blink 2 times<br />
var anim = dojo.fx.chain( [<br />
dojo.fadeOut( { node: 'token_'+token.x+'_'+token.y } ),<br />
dojo.fadeIn( { node: 'token_'+token.x+'_'+token.y } ),<br />
dojo.fadeOut( { <br />
node: 'token_'+token.x+'_'+token.y,<br />
onEnd: function( node ) {<br />
<br />
// Remove any color class<br />
dojo.removeClass( node, [ 'tokencolor_000000', 'tokencolor_ffffff' ] );<br />
// ... and add the good one<br />
dojo.addClass( node, 'tokencolor_'+targetColor );<br />
<br />
} <br />
} ),<br />
dojo.fadeIn( { node: 'token_'+token.x+'_'+token.y } )<br />
<br />
] ); // end of dojo.fx.chain<br />
<br />
// ... and launch the animation<br />
anim.play(); <br />
}<br />
},<br />
</pre><br />
<br />
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].<br />
<br />
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()".</div>Christopheryoderhttp://en.doc.boardgamearena.com/index.php?title=Tutorial_reversi&diff=1363Tutorial reversi2015-02-05T16:46:17Z<p>Christopheryoder: /* The rules */</p>
<hr />
<div><br />
== Introduction ==<br />
<br />
Using this tutorial, you can build a complete working game on the BGA environment: Reversi.<br />
<br />
Before you read this tutorial, you must:<br />
* Read the overall presentations of the BGA Framework ([[Studio|see here]]).<br />
* Know the [http://en.wikipedia.org/wiki/Reversi#Rules rules of Reversi].<br />
* Know the languages used on BGA: PHP, SQL, HTML, CSS, Javascript.<br />
<br />
== Create your first game ==<br />
<br />
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 this 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.<br />
<br />
Thus, you can start a "Reversi" game, and arrive on a void, empty game. Yeah.<br />
<br />
== Let it look like Reversi ==<br />
<br />
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.<br />
<br />
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).<br />
<br />
For Reversi, it's useless to have a 750x750px board - much too big, so we choose this one which fit perfectly (536x528):<br />
<br />
[[File:Board.jpg]]<br />
<br />
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.<br />
<br />
Now, let's make it appears on our game:<br />
* upload board.jpg in your "img/" directory.<br />
* edit "reversi_reversi.tpl" to add a 'div' for your board:<br />
<br />
<pre><br />
<div id="board"><br />
</div><br />
</pre><br />
<br />
* edit your reversi.css file to transform it into a visible board:<br />
<br />
#board {<br />
width: 536px;<br />
height: 528px;<br />
background-image: url('img/board.jpg');<br />
}<br />
<br />
Refresh your page. Here's your board:<br />
<br />
[[File:reversi1.jpg]]<br />
<br />
== Make the squares appears ==<br />
<br />
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. <br />
Obviously, we need 64 squares. To avoid writing 64 'div' elements on our template, we are going to use the "block" feature.<br />
<br />
Let's modify our template like this:<br />
<br />
<pre><br />
<div id="board"><br />
<!-- BEGIN square --><br />
<div id="square_{X}_{Y}" class="square" style="left: {LEFT}px; top: {TOP}px;"></div><br />
<!-- END square --><br />
</div><br />
</pre><br />
<br />
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.<br />
<br />
Let's do it in our "reversi.view.php" file:<br />
<br />
<pre><br />
$this->page->begin_block( "reversi_reversi", "square" );<br />
<br />
$hor_scale = 64.8;<br />
$ver_scale = 64.4;<br />
for( $x=1; $x<=8; $x++ )<br />
{<br />
for( $y=1; $y<=8; $y++ )<br />
{<br />
$this->page->insert_block( "square", array(<br />
'X' => $x,<br />
'Y' => $y,<br />
'LEFT' => round( ($x-1)*$hor_scale+10 ),<br />
'TOP' => round( ($y-1)*$ver_scale+7 )<br />
) );<br />
} <br />
}<br />
</pre><br />
<br />
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.<br />
<br />
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:<br />
<br />
<pre><br />
#board {<br />
width: 536px;<br />
height: 528px;<br />
background-image: url('img/board.jpg');<br />
position: relative;<br />
}<br />
<br />
.square {<br />
width: 62px;<br />
height: 62px;<br />
position: absolute;<br />
background-color: red;<br />
}<br />
</pre><br />
<br />
Explanations:<br />
* With "position: relative" on board, we ensure square elements are positioned relatively to board.<br />
* 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.<br />
<br />
Let's refresh and check our our (beautiful) squares:<br />
<br />
[[File:reversi2.jpg]]<br />
<br />
== The discs ==<br />
<br />
Now, our board is ready to receive some disc tokens!<br />
<br />
At first, we introduce a new 'div' element as a child of "board" to host all these tokens (in our template):<br />
<br />
<pre><br />
<!-- END square --><br />
<br />
<div id="tokens"><br />
</div><br />
</div><br />
</pre><br />
<br />
Then, let's introduce a new piece of art with the discs. We need some transparency here so we are using a png file:<br />
<br />
[[File:tokens.png]]<br />
<br />
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].<br />
<br />
Now, let's separate the disc with some CSS stuff:<br />
<br />
<pre><br />
.token {<br />
width: 56px;<br />
height: 56px;<br />
position: absolute;<br />
background-image: url('img/tokens.png');<br />
}<br />
.tokencolor_ffffff { background-position: 0px 0px; }<br />
.tokencolor_000000 { background-position: -56px 0px; }<br />
</pre><br />
<br />
With this CSS code, we apply the classes "token" and "tokencolor_ffffff" to a div element and we've got a white token. Yeah.<br />
<br />
Note the "position: absolute" which allows us to position tokens on the board and make them "slide" to their positions.<br />
<br />
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".<br />
<br />
In our template file (reversi_reversi.tpl), let's create the piece of HTML needed to display our token:<br />
<br />
<pre><br />
<script type="text/javascript"><br />
<br />
// Templates<br />
<br />
var jstpl_token='<div class="token tokencolor_${color}" id="token_${x_y}"></div>';<br />
<br />
</script><br />
</pre><br />
<br />
Note: we already created the "templates" section for you in the game skeleton.<br />
<br />
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).<br />
<br />
Now, let's create a method in our Javascript code that will make a token appear on the board, using this template:<br />
<br />
<pre><br />
addTokenOnBoard: function( x, y, player )<br />
{<br />
dojo.place( this.format_block( 'jstpl_token', {<br />
x_y: x+'_'+y,<br />
color: this.gamedatas.players[ player ].color<br />
} ) , 'tokens' );<br />
<br />
this.placeOnObject( 'token_'+x+'_'+y, 'overall_player_board_'+player );<br />
this.slideToObject( 'token_'+x+'_'+y, 'square_'+x+'_'+y ).play();<br />
},<br />
</pre><br />
<br />
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.<br />
<br />
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.<br />
<br />
Note: don't forget to call the "play()", otherwise the token remains at its original location.<br />
<br />
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.<br />
<br />
Before we can show a token, we need to set the player colors in the setupNewGame function in reversi.game.php:<br />
<pre><br />
$default_colors = array( "ffffff", "000000" );<br />
</pre><br />
<br />
Now, to test if everything works fine, just call "this.addTokenOnBoard( 2, 2, <your_player_id> )" in your "setup" Javascript method, and reload the page. A token should appear and slide immediately to its position, like this:<br />
<br />
[[File:reversi3.jpg]]<br />
<br />
== The database ==<br />
<br />
We did most of the client-side programming, so let's have a look on the other side now.<br />
<br />
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.<br />
<br />
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.<br />
<br />
[[File:reversi4.jpg]]<br />
<br />
The database model of Reversi is very simple: just one table with the squares of the board. In our dbmodel.sql, we have this:<br />
<br />
<pre><br />
CREATE TABLE IF NOT EXISTS `board` (<br />
`board_x` smallint(5) unsigned NOT NULL,<br />
`board_y` smallint(5) unsigned NOT NULL,<br />
`board_player` int(10) unsigned DEFAULT NULL,<br />
PRIMARY KEY (`board_x`,`board_y`)<br />
) ENGINE=InnoDB;<br />
</pre><br />
<br />
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.<br />
<br />
== Setup the initial game position ==<br />
<br />
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).<br />
<br />
Let's do this:<br />
<br />
<pre><br />
// Init the board<br />
$sql = "INSERT INTO board (board_x,board_y,board_player) VALUES ";<br />
$sql_values = array();<br />
list( $blackplayer_id, $whiteplayer_id ) = array_keys( $players );<br />
for( $x=1; $x<=8; $x++ )<br />
{<br />
for( $y=1; $y<=8; $y++ )<br />
{<br />
$token_value = "NULL";<br />
if( ($x==4 && $y==4) || ($x==5 && $y==5) ) // Initial positions of white player<br />
$token_value = "'$whiteplayer_id'";<br />
else if( ($x==4 && $y==5) || ($x==5 && $y==4) ) // Initial positions of black player<br />
$token_value = "'$blackplayer_id'";<br />
<br />
$sql_values[] = "('$x','$y',$token_value)";<br />
}<br />
}<br />
$sql .= implode( $sql_values, ',' );<br />
self::DbQuery( $sql );<br />
<br />
<br />
// Active first player<br />
self::activeNextPlayer(); <br />
</pre><br />
<br />
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.<br />
<br />
At the end, we call activeNextPlayer to make the first player active at the beginning of the game.<br />
<br />
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):<br />
<br />
<pre><br />
// Get reversi board token<br />
$result['board'] = self::getObjectListFromDB( "SELECT board_x x, board_y y, board_player player<br />
FROM board<br />
WHERE board_player IS NOT NULL" );<br />
</pre><br />
<br />
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.<br />
<br />
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:<br />
<br />
<pre><br />
for( var i in gamedatas.board )<br />
{<br />
var square = gamedatas.board[i];<br />
<br />
if( square.player !== null )<br />
{<br />
this.addTokenOnBoard( square.x, square.y, square.player );<br />
}<br />
}<br />
</pre><br />
<br />
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.<br />
<br />
Reload... and here we are:<br />
<br />
[[File:reversi5.jpg]]<br />
<br />
It starts to smell Reversi here...<br />
<br />
== The game state machine ==<br />
<br />
Now, let's stop our game again, because we are going to start the core game logic.<br />
<br />
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 although. Here's a diagram of our game state machine:<br />
<br />
[[File:reversi6.jpg]]<br />
<br />
And here's our "states.inc.php", according to this diagram:<br />
<br />
<pre><br />
$machinestates = array(<br />
<br />
1 => array(<br />
"name" => "gameSetup",<br />
"description" => clienttranslate("Game setup"),<br />
"type" => "manager",<br />
"action" => "stGameSetup",<br />
"transitions" => array( "" => 10 )<br />
),<br />
<br />
10 => array(<br />
"name" => "playerTurn",<br />
"description" => clienttranslate('${actplayer} must play a disc'),<br />
"descriptionmyturn" => clienttranslate('${you} must play a disc'),<br />
"type" => "activeplayer",<br />
"args" => "argPlayerTurn",<br />
"possibleactions" => array( 'playDisc' ),<br />
"transitions" => array( "playDisc" => 11, "zombiePass" => 11 )<br />
),<br />
<br />
11 => array(<br />
"name" => "nextPlayer",<br />
"type" => "game",<br />
"action" => "stNextPlayer",<br />
"updateGameProgression" => true, <br />
"transitions" => array( "nextTurn" => 10, "cantPlay" => 11, "endGame" => 99 )<br />
),<br />
<br />
99 => array(<br />
"name" => "gameEnd",<br />
"description" => clienttranslate("End of game"),<br />
"type" => "manager",<br />
"action" => "stGameEnd",<br />
"args" => "argGameEnd"<br />
)<br />
<br />
);<br />
</pre><br />
<br />
Now, let's create in reversi.game.php the methods that are declared in this game states description file:<br />
* argPlayerTurn<br />
* stNextPlayer<br />
<br />
... and start a new Reversi game.<br />
<br />
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"):<br />
<br />
[[File:reversi7.jpg]]<br />
<br />
== The rules ==<br />
<br />
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:<br />
* As we just said, to help the player to see where he can play.<br />
* When the player play, to check if he has the right to play here.<br />
<br />
This is pure PHP programming here, and there's 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:<br />
* 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.<br />
* 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.<br />
<br />
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.<br />
<br />
If you want to look into details, please look at the "utility method" sections of reversi.game.php.<br />
<br />
== Display allowed moves ==<br />
<br />
Now, what we want to do is highlight squares where player can place a disc.<br />
<br />
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:<br />
<br />
<pre><br />
<br />
function argPlayerTurn()<br />
{<br />
return array(<br />
'possibleMoves' => self::getPossibleMoves( self::getActivePlayerId() )<br />
);<br />
}<br />
</pre><br />
<br />
We are of course using the "getPossibleMoves" method we just developed.<br />
<br />
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:<br />
<br />
<pre><br />
onEnteringState: function( stateName, args )<br />
{<br />
console.log( 'Entering state: '+stateName );<br />
<br />
switch( stateName )<br />
{<br />
case 'playerTurn':<br />
this.updatePossibleMoves( args.args.possibleMoves );<br />
break;<br />
}<br />
},<br />
</pre><br />
<br />
So, when we are entering into "playerTurn" game state, we are calling our "updatePossibleMoves" method. This method looks like this:<br />
<br />
<pre><br />
updatePossibleMoves: function( possibleMoves )<br />
{<br />
// Remove current possible moves<br />
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );<br />
<br />
for( var x in possibleMoves )<br />
{<br />
for( var y in possibleMoves[ x ] )<br />
{<br />
// x,y is a possible move<br />
dojo.addClass( 'square_'+x+'_'+y, 'possibleMove' );<br />
} <br />
}<br />
<br />
this.addTooltipToClass( 'possibleMove', '', _('Place a disc here') );<br />
},<br />
</pre><br />
<br />
The idea here is that we've created a CSS class ("possibleMove") that can be applied to a "square" element to highlight it:<br />
<pre><br />
.possibleMove {<br />
background-color: white;<br />
opacity: 0.2;<br />
filter:alpha(opacity=20); /* For IE8 and earlier */ <br />
cursor: pointer; <br />
}<br />
</pre><br />
<br />
At first, we remove all "possibleMove" classes currently applied with the very useful combination of "dojo.query" and "removeClass" method.<br />
<br />
Then we loop through all possible moves our PHP "updatePossibleMoves" function created for us, and add the "possibleMove" class to each corresponding square.<br />
<br />
Finally, we use the BGA framework "addTooltipToClass" method to associate a tooltip to all those highlighted squares so that players can understand their meaning.<br />
<br />
And here we are:<br />
<br />
[[File:reversi8.jpg.jpg]]<br />
<br />
== Let's play ==<br />
<br />
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:<br />
* When we click on a "possibleMove" square, send the move to the server.<br />
* Server side, check the move is correct, apply Reversi rules and jump to next player.<br />
* Client side, change the disc position to reflect the move.<br />
<br />
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:<br />
<br />
<pre><br />
dojo.query( '.square' ).connect( 'onclick', this, 'onPlayDisc' );<br />
</pre><br />
<br />
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.<br />
<br />
Here's our "onPlayDisc" method below:<br />
<br />
<pre><br />
onPlayDisc: function( evt )<br />
{<br />
// Stop this event propagation<br />
dojo.stopEvent( evt );<br />
<br />
// Get the cliqued square x and y<br />
// Note: square id format is "square_X_Y"<br />
var coords = evt.currentTarget.id.split('_');<br />
var x = coords[1];<br />
var y = coords[2];<br />
<br />
if( ! dojo.hasClass( 'square_'+x+'_'+y, 'possibleMove' ) )<br />
{<br />
// This is not a possible move => the click does nothing<br />
return ;<br />
}<br />
<br />
if( this.checkAction( 'playDisc' ) ) // Check that this action is possible at this moment<br />
{ <br />
this.ajaxcall( "/reversi/reversi/playDisc.html", {<br />
x:x,<br />
y:y<br />
}, this, function( result ) {} );<br />
} <br />
},<br />
</pre><br />
<br />
What we do here is:<br />
* We stop the propagation of the Javascript "onclick" event. Otherwise, it can lead to random behavior so it's always a good idea.<br />
* We get the x/y coordinates of the square by using "evt.currentTarget.id".<br />
* We check that clicked square has the "possibleMove" class, otherwise we know for sure that we can't play there.<br />
* 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.<br />
* Finally, we make a call to the server using BGA "ajaxcall" method with argument x and y.<br />
<br />
Now, we have to manage this "playDisc" action on server side. At first, we introduce a "playDisc" entry point in our "reversi.action.php":<br />
<br />
<pre><br />
public function playDisc()<br />
{<br />
self::setAjaxMode(); <br />
$x = self::getArg( "x", AT_posint, true );<br />
$y = self::getArg( "y", AT_posint, true );<br />
$result = $this->game->playDisc( $x, $y );<br />
self::ajaxResponse( );<br />
}<br />
</pre><br />
<br />
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.<br />
<br />
Now, let's have a look of this playDisc method:<br />
<br />
<pre><br />
function playDisc( $x, $y )<br />
{<br />
// Check that this player is active and that this action is possible at this moment<br />
self::checkAction( 'playDisc' ); <br />
</pre><br />
<br />
... 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).<br />
<br />
<pre><br />
// Now, check if this is a possible move<br />
$board = self::getBoard();<br />
$player_id = self::getActivePlayerId();<br />
$turnedOverDiscs = self::getTurnedOverDiscs( $x, $y, $player_id, $board );<br />
<br />
if( count( $turnedOverDiscs ) > 0 )<br />
{<br />
// This move is possible!<br />
</pre><br />
<br />
...now, we are using the "getTurnedOverDiscs" method again to check that this move is possible.<br />
<br />
<pre><br />
// Let's place a disc at x,y and return all "$returned" discs to the active player<br />
<br />
$sql = "UPDATE board SET board_player='$player_id'<br />
WHERE ( board_x, board_y) IN ( ";<br />
<br />
foreach( $turnedOverDiscs as $turnedOver )<br />
{<br />
$sql .= "('".$turnedOver['x']."','".$turnedOver['y']."'),";<br />
}<br />
$sql .= "('$x','$y') ) ";<br />
<br />
self::DbQuery( $sql );<br />
<br />
</pre><br />
<br />
... we update the database to change the color of all turned over disc + the disc we just placed.<br />
<br />
<pre><br />
// Update scores according to the number of disc on board<br />
$sql = "UPDATE player<br />
SET player_score = (<br />
SELECT COUNT( board_x ) FROM board WHERE board_player=player_id<br />
)";<br />
self::DbQuery( $sql );<br />
<br />
// Statistics<br />
self::incStat( count( $turnedOverDiscs ), "turnedOver", $player_id );<br />
if( ($x==1 && $y==1) || ($x==8 && $y==1) || ($x==1 && $y==8) || ($x==8 && $y==8) )<br />
self::incStat( 1, 'discPlayedOnCorner', $player_id );<br />
else if( $x==1 || $x==8 || $y==1 || $y==8 )<br />
self::incStat( 1, 'discPlayedOnBorder', $player_id );<br />
else if( $x>=3 && $x<=6 && $y>=3 && $y<=6 )<br />
self::incStat( 1, 'discPlayedOnCenter', $player_id );<br />
<br />
</pre><br />
<br />
... now, we update both player score by counting all disc, and we manage game statistics.<br />
<br />
<pre><br />
// Notify<br />
self::notifyAllPlayers( "playDisc", clienttranslate( '${player_name} plays a disc and turns over ${returned_nbr} disc(s)' ), array(<br />
'player_id' => $player_id,<br />
'player_name' => self::getActivePlayerName(),<br />
'returned_nbr' => count( $turnedOverDiscs ),<br />
'x' => $x,<br />
'y' => $y<br />
) );<br />
<br />
self::notifyAllPlayers( "turnOverDiscs", '', array(<br />
'player_id' => $player_id,<br />
'turnedOver' => $turnedOverDiscs<br />
) );<br />
<br />
$newScores = self::getCollectionFromDb( "SELECT player_id, player_score FROM player", true );<br />
self::notifyAllPlayers( "newScores", "", array(<br />
"scores" => $newScores<br />
) );<br />
</pre><br />
<br />
... 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.<br />
<br />
<pre><br />
// Then, go to the next state<br />
$this->gamestate->nextState( 'playDisc' );<br />
}<br />
else<br />
throw new feException( "Impossible move" );<br />
}<br />
</pre><br />
<br />
... 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).<br />
To make the statistics work, we have to initialize them in state.inc.php:<br />
<br />
<pre><br />
// Statistics existing for each player<br />
"player" => array(<br />
<br />
"discPlayedOnCorner" => array( "id"=> 10,<br />
"name" => totranslate("Discs played on a corner"), <br />
"type" => "int" ),<br />
<br />
"discPlayedOnBorder" => array( "id"=> 11,<br />
"name" => totranslate("Discs played on a border"), <br />
"type" => "int" ),<br />
<br />
"discPlayedOnCenter" => array( "id"=> 12,<br />
"name" => totranslate("Discs played on board center part"), <br />
"type" => "int" ),<br />
<br />
"turnedOver" => array( "id"=> 13,<br />
"name" => totranslate("Number of discs turned over"), <br />
"type" => "int" ) <br />
)<br />
</pre><br />
<br />
A last thing to do on the server side is to activate the next player when we enter the "nextPlayer" game state:<br />
<br />
<pre><br />
function stNextPlayer()<br />
{<br />
// Activate next player<br />
$player_id = self::activeNextPlayer();<br />
<br />
self::giveExtraTime( $player_id );<br />
$this->gamestate->nextState( 'nextTurn' );<br />
<br />
}<br />
</pre><br />
<br />
Now, when we play a disc, the rules are checked and the disc appears in the database.<br />
<br />
[[File:reversi9.jpg]]<br />
<br />
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.<br />
<br />
== Make the move appear automatically ==<br />
<br />
Now, what we have to do is process the notifications sent by the server and make the move appear on the interface.<br />
<br />
In our "setupNotifications" method, we register 2 methods for the 2 notifications we created at the previous step ('playDisc' and 'turnOverDiscs'):<br />
<br />
<pre><br />
dojo.subscribe( 'playDisc', this, "notif_playDisc" );<br />
this.notifqueue.setSynchronous( 'playDisc', 500 );<br />
dojo.subscribe( 'turnOverDiscs', this, "notif_turnOverDiscs" );<br />
this.notifqueue.setSynchronous( 'turnOverDiscs', 1500 );<br />
</pre><br />
<br />
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:<br />
* Make a disc slide from the player panel to its place on the board<br />
* (wait 500ms)<br />
* Make all turned over discs blink (and of course turned them over)<br />
* (wait 1500ms)<br />
* Let the next player play.<br />
<br />
Let's have a look now on the "playDisc" notification handler method:<br />
<br />
<pre><br />
notif_playDisc: function( notif )<br />
{<br />
// Remove current possible moves (makes the board more clear)<br />
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' ); <br />
<br />
this.addTokenOnBoard( notif.args.x, notif.args.y, notif.args.player_id );<br />
},<br />
</pre><br />
<br />
No surprise here, we re-used some existing stuff to:<br />
* Remove the highlighted squares.<br />
* Add a new disc on board, coming from player panel.<br />
<br />
Now, here's the method that handles the turnOverDiscs notification:<br />
<br />
<pre><br />
notif_turnOverDiscs: function( notif )<br />
{<br />
// Get the color of the player who is returning the discs<br />
var targetColor = this.gamedatas.players[ notif.args.player_id ].color;<br />
<br />
// Make these discs blink and set them to the specified color<br />
for( var i in notif.args.turnedOver )<br />
{<br />
var token = notif.args.turnedOver[ i ];<br />
<br />
// Make the token blink 2 times<br />
var anim = dojo.fx.chain( [<br />
dojo.fadeOut( { node: 'token_'+token.x+'_'+token.y } ),<br />
dojo.fadeIn( { node: 'token_'+token.x+'_'+token.y } ),<br />
dojo.fadeOut( { <br />
node: 'token_'+token.x+'_'+token.y,<br />
onEnd: function( node ) {<br />
<br />
// Remove any color class<br />
dojo.removeClass( node, [ 'tokencolor_000000', 'tokencolor_ffffff' ] );<br />
// ... and add the good one<br />
dojo.addClass( node, 'tokencolor_'+targetColor );<br />
<br />
} <br />
} ),<br />
dojo.fadeIn( { node: 'token_'+token.x+'_'+token.y } )<br />
<br />
] ); // end of dojo.fx.chain<br />
<br />
// ... and launch the animation<br />
anim.play(); <br />
}<br />
},<br />
</pre><br />
<br />
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].<br />
<br />
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()".</div>Christopheryoderhttp://en.doc.boardgamearena.com/index.php?title=First_steps_with_BGA_Studio&diff=1362First steps with BGA Studio2015-02-04T17:26:03Z<p>Christopheryoder: /* Connect to your SFTP folder */</p>
<hr />
<div>== Connect to the BGA Studio website ==<br />
<br />
Go to BGA Studio website:<br />
http://en.studio.boardgamearena.com<br />
<br />
Choose one of your 10 accounts (ex: myusername0), and login into the website - as you would do for Board Game Arena.<br />
<br />
== Check projects in progress and available game licences ==<br />
<br />
On the left menu, you can check game projects under development and available game licences. From this point, you can choose what you want to do:<br />
* Join an existing project.<br />
* Create a new project.<br />
* Try to get a licence for a game you don't see in the "available game licences" page (see how-to on "available licences" page).<br />
<br />
== Create a new game project ==<br />
<br />
You can do most of projects-related operation from "Control Panel / Manage games". In particular, you can create a new project automatically from there.<br />
<br />
== Connect to your SFTP folder == <br />
<br />
From the initial email from the Studio you get:<br />
* the name of the SFTP server to connect to<br />
* your SFTP login and password<br />
<br />
Using this information:<br />
# Connect to the SFTP server using your SFTP login and password, through your favourite SFTP client software (such as [http://winscp.net/ WinSCP] for example)<br />
# Check that your home folder contains one folder for each of the three example games (reversi, hearts, gomoku). If you have already created a new game project, one additional folder should be in your "home" folder.<br />
<br />
== Let's code! ==<br />
<br />
Now, you can try to launch a new game on BGA Studio from the "Play now" menu entry, as you would do on Board Game Arena website.<br />
<br />
# Find your game in the 'Play now' section and launch a table<br />
# Use the 'I want between X and X' players to tick down the maximum players number to the minimum<br />
# Click 'Express start': your game launches with the maximum number of players specified. It shows an empty canvas: in the game zone you just have a sentence 'This is your game interface. You can edit this HTML in your ".tpl" file.'.<br />
# Switch to your SFTP home folder, go into your game folder. Edit the game_game.tpl file, and change this sentence to 'Hey, this is my first game!', then save.<br />
# Go back to your browser and refresh, check that the game zone has updated.<br />
# Click on the 'Exit game' icon on the top right, and in the popup choose 'Express game stop'. The game ends automatically and you are brought back to the table screen for this ended game.<br />
# Switch to your game folder, go into the img folder and overwrite your game_box.png file with another image.<br />
# Go back to your browser, '''empty your browser cache''', then refresh the page, and check that the game box image has been updated.<br />
<br />
Then you can modify the provided skeleton and begin to develop your game :)<br />
<br />
== Commit your changes ==<br />
<br />
Committing uploads your changes on our [http://en.wikipedia.org/wiki/Revision_control revision control] system. This is an extra assurance not to lose your code, and to have the possibility to get a previous version of your code if you need to backtrack. It also helps us to follow your progress (we get an email when you commit). So you should commit from time to time, when you hit some landmark in your development.<br />
<br />
You can automatically commit your sources in the repository from "Control Panel / Manage Games / Your games / Commit my modifications". Then:<br />
<br />
# Enter your commit comment (such as 'My first commit') then hit the 'Submit' button;<br />
# Check the log for errors, it should end with the following lines:<br />
<br />
Transmitting file data .<br />
Committed revision #revision number#.<br />
HAL says: done.<br />
<br />
<br />
== That's all! ==<br />
<br />
Now you know about the basics of updating your game on BGA Studio and testing your changes.<br />
<br />
For more information on the specificites of each file, please check out the [[Studio#BGA_Studio_documentation | reference documentation for the framework]].</div>Christopheryoderhttp://en.doc.boardgamearena.com/index.php?title=Gamehelpdragonheart&diff=96Gamehelpdragonheart2012-04-30T20:53:02Z<p>Christopheryoder: /* Cards */</p>
<hr />
<div>==Summary==<br />
Dragonheart is a two player card game where the goal is to collect as many points as possible by placing your cards on the board and collecting the cards already placed there. There are 9 different cards, each with their own rules as to which cards can be collected when they are placed down.<br />
<br />
==Goal==<br />
To have the most points by the end of the game.<br />
<br />
==Game Start==<br />
At the start of the game, each player takes five cards from their deck and the Great Dragon piece is put on the board.<br />
<br />
==End==<br />
The game ends when all nine ship cards have been used, or one players deck is exhausted. At that point, each player adds the value of all the cards in their respective piles, plus 2 extra points to whomever has the Great Dragon piece. Whoever has the most points, wins the game.<br />
<br />
==Turns==<br />
Players alternate turns, putting down and picking up cards. A player may choose to put down as many cards of the same type as he or she wants to. The cards get placed on their corresponding picture on the game board. Depending on what was placed, a player may take cards from the board to put in their pile, or move cards to the bottom of the board, below the ship. <br />
<br />
==Cards==<br />
There are five types of cards in the game. Cards have a point value to them listed as a number in the corner, that is unrelated to what type of card it is. Arrows on the board indicate what cards can take what.<br />
<br />
* ''Dwarf'': The player who places the fourth dwarf on the board, takes all four of the dwarf cards. No other card allows a player to take a dwarf.<br />
* ''Huntress'': The player who places the third huntress card, takes all fire dragon cards from the board. At that point, the three huntress cards are moved to the bottom of the board. <br />
* ''Fire Dragon'': Each time a fire dragon is placed, the player takes all of the treasure chest cards. <br />
* ''Treasure Chest'': Placing this card has no action, but it can be taken by a fire dragon or sorceress.<br />
* ''Troll'': Placing this card allows the player to take the sorceress pile.<br />
* ''Knight'': The player who places the second knight card, may choose to take either the sorceress or troll pile. Afterwards, the two knight cards are placed at the bottom of the board.<br />
* ''Petrified Dragon'': Placing this card has no effect, but when it is taken by a sorceress, the Great Dragon piece is taken too, either from the board or from the opponent.<br />
* ''Sorceress'': Placing a sorceress allows the player to take either the petrified dragon pile, or the treasure pile. Taking the petrified dragon cards (if there are any on the board) gives the player possession of the Great Dragon.<br />
* ''Ship'': The third ship card placed, allows the player to take all the knight and huntress cards placed at the bottom of the deck. The ship cards are then discarded. The third time that three ship cards were played ends the game.<br />
* ''Great Dragon'': The great dragon piece goes to the last player to take a petrified dragon stack. Possession of the Great Dragon gives the player an extra card, plus three extra points at the end of the game. If the dragon is taken from an opponent, then the player gets a random card from the opponents hand.</div>Christopheryoder