Board Game Arena - Příspěvky [cs]

Gamehelpgearnpiston

2013-04-19T13:20:28Z

Pikiou: Introduction sentence

It is 1888, and everywhere you turn, people are talking about the horseless carriage. The players build an automobile prototype by patenting new parts, scavenging in the junk yard, and looking for opportunities to trip up their fellow automotive pioneers, all the while seeking to impress investors that are looking to get into car production. Gear & Piston is a simple, yet engaging 30-60 minute game for 2-6 players, and is [http://www.kickstarter.com/projects/ludicreations/gear-and-piston-board-game now on Kickstarter].
===QUICK RULES REFERENCE===
====ROUND SEQUENCE AND PHASES====
*I. Plan actions.
*II. Resolve actions.
*III. Refresh Patent Office and Junk Yard.
====LOCATION ACTIONS====
*Back Alley: Choose 1 action from the following. The Action Token placed in the Back Alley cannot be used during the next planning phase.
**Black Market (draw 3 New Parts and keep 1),
**Espionage (steal a part from another player),
**or Union Muscle (move Action Token ahead or behind in a location).
*Patent Office: Take 1 New Part, either from the parts next to the game or from the New Parts stack.
*Junk Yard: Take up to 2 Junk Parts, either from the parts next to the game or from the New Parts stack.
*Workshop: Actions that may be used are Build, Dismantle, and Upgrade.
====REQUIREMENTS OF A COMPLETE AUTOMOBILE====
* Each automobile requires a Motor, Fuel supply for each Motor, Steering, Gear and two Axles.
* Each type of part (electric, gasoline, steam) requires a Motor and Supply of same type.
* Each part on the top row requires a part on the bottom row and vice versa.
* Each Axle supports only the five parts surrounding it.
====GAME END====
*There are not enough tiles to refill a location from the refill Stack.
OR
*One of the players has a complete automobile with at least twelve parts on it.
====SCORING====
* VP according to Investors
* +1 VP for each part in one largest continuous area
* -1 VP for each point of Volatility

Gamehelpgearnpiston

2013-04-19T13:18:14Z

Pikiou: Smaller titles

===QUICK RULES REFERENCE===
====ROUND SEQUENCE AND PHASES====
*I. Plan actions.
*II. Resolve actions.
*III. Refresh Patent Office and Junk Yard.
====LOCATION ACTIONS====
*Back Alley: Choose 1 action from the following. The Action Token placed in the Back Alley cannot be used during the next planning phase.
**Black Market (draw 3 New Parts and keep 1),
**Espionage (steal a part from another player),
**or Union Muscle (move Action Token ahead or behind in a location).
*Patent Office: Take 1 New Part, either from the parts next to the game or from the New Parts stack.
*Junk Yard: Take up to 2 Junk Parts, either from the parts next to the game or from the New Parts stack.
*Workshop: Actions that may be used are Build, Dismantle, and Upgrade.
====REQUIREMENTS OF A COMPLETE AUTOMOBILE====
* Each automobile requires a Motor, Fuel supply for each Motor, Steering, Gear and two Axles.
* Each type of part (electric, gasoline, steam) requires a Motor and Supply of same type.
* Each part on the top row requires a part on the bottom row and vice versa.
* Each Axle supports only the five parts surrounding it.
====GAME END====
*There are not enough tiles to refill a location from the refill Stack.
OR
*One of the players has a complete automobile with at least twelve parts on it.
====SCORING====
* VP according to Investors
* +1 VP for each part in one largest continuous area
* -1 VP for each point of Volatility

Gamehelpgearnpiston

2013-04-19T13:01:05Z

Pikiou: Created page with "=QUICK RULES REFERENCE= ==ROUND SEQUENCE AND PHASES== *I. Plan actions. *II. Resolve actions. *III. Refresh Patent Office and Junk Yard. ==LOCATION ACTIONS== *Back Alley: Choo..."

=QUICK RULES REFERENCE=
==ROUND SEQUENCE AND PHASES==
*I. Plan actions.
*II. Resolve actions.
*III. Refresh Patent Office and Junk Yard.
==LOCATION ACTIONS==
*Back Alley: Choose 1 action from the following. The Action Token placed in the Back Alley cannot be used during the next planning phase.
**Black Market (draw 3 New Parts and keep 1),
**Espionage (steal a part from another player),
**or Union Muscle (move Action Token ahead or behind in a location).
*Patent Office: Take 1 New Part, either from the parts next to the game or from the New Parts stack.
*Junk Yard: Take up to 2 Junk Parts, either from the parts next to the game or from the New Parts stack.
*Workshop: Actions that may be used are Build, Dismantle, and Upgrade.
==REQUIREMENTS OF A COMPLETE AUTOMOBILE==
* Each automobile requires a Motor, Fuel supply for each Motor, Steering, Gear and two Axles.
* Each type of part (electric, gasoline, steam) requires a Motor and Supply of same type.
* Each part on the top row requires a part on the bottom row and vice versa.
* Each Axle supports only the five parts surrounding it.
==GAME END==
*There are not enough tiles to refill a location from the refill Stack.
OR
*One of the players has a complete automobile with at least twelve parts on it.
==SCORING==
* VP according to Investors
* +1 VP for each part in one largest continuous area
* -1 VP for each point of Volatility

Main game logic: yourgamename.game.php

2013-04-18T14:32:20Z

Pikiou: /* Game states and active players */ Precision on setPlayersMultiactive

This file is the main file for your game logic. Here you initialize the game, persist data, implement the rules and notify changes to the client interface.

== File Structure ==

The details on how the file is structured is described directly with comments on the code skeleton provided to you.

Basically, here's this structure:
* EmptyGame (constructor): where you define global variables.
* setupNewGame: initial setup of the game.
* getAllDatas: where you retrieve all game data during a complete reload of the game.
* getGameProgression: where you compute the game progression indicator.
* Utility functions: your utility functions.
* Player actions: the entry points for players actions.
* Game state arguments: methods to return additional data on specific game states.
* Game state actions: the logic to run when entering a new game state.
* zombieTurn: what to do it's the turn of a zombie player.

== Accessing player informations ==

; getPlayersNumber()
: Returns the number of players playing at the table
: Note: doesn't work in setupNewGame so use count($players) instead

; getActivePlayerId()
: Get the "active_player", whatever what is the current state type.
: Note: it does NOT mean that this player is active right now, because state type could be "game" or "multiplayer"
: Note: avoid using this method in a "multiplayer" state because it does not mean anything.

; getActivePlayerName()
: Get the "active_player" name
: Note: avoid using this method in a "multiplayer" state because it does not mean anything.

; loadPlayersBasicInfos()
: Get an associative array with generic data about players (ie: not game specific data).
: The key of the associative array is the player id.
: The content of each value is:
: * player_name
: * player_color (ex: ff0000)

; getCurrentPlayerId()
: Get the "current_player". The current player is the one from which the action originated (the one who send the request).
: '''Be careful''': It is not always the active player.
: In general, you shouldn't use this method, unless you are in "multiplayer" state.

; getCurrentPlayerName()
: Get the "current_player" name
: Be careful using this method (see above).

; getCurrentPlayerColor()
: Get the "current_player" color
: Be careful using this method (see above).

; isCurrentPlayerZombie()
: Check the "current_player" zombie status. If true, player leave the game.

== Accessing database ==

The main game logic should be the only point from where you should access to the game database. You access your database using SQL queries with the methods below.

'''IMPORTANT'''

BGA is using [http://dev.mysql.com/doc/refman/5.0/en/sql-syntax-transactions.html database transactions]. It means that your database changes WON'T BE APPLIED to the database until your request ends normally. Using transaction is in fact very useful for you: at any time, if your game logic detects that something is wrong (ex: unallowed move), you just have to throw an exception and all the changes already performed on the game situation will be removed.

; DbQuery( $sql )
: This is the generic method to access the database.
: It can execute any type of SELECT/UPDATE/DELETE/REPLACE query on the database.
: You should use it for UPDATE/DELETE/REPLACE query. For SELECT queries, the specialized methods above are much better.

; getUniqueValueFromDB( $sql )
: Returns a unique value from DB or null if no value is found.
: $sql must be a SELECT query.
: Raise an exception if more than 1 row is returned.

; getCollectionFromDB( $sql, $bSingleValue=false )
: Returns an associative array of rows for a sql SELECT query.
: The key of the resulting associative array is the first field specified in the SELECT query.
: The value of the resulting associative array if an associative array with all the field specified in the SELECT query and associated values.
: First column must be a primary or alternate key.
: The resulting collection can be empty.
: If you specified $bSingleValue=true and if your SQL query request 2 fields A and B, the method returns an associative array "A=>B"

Example 1:
<pre>
self::getCollectionFromDB( "SELECT player_id id, player_name name, player_score score FROM player" );

Result:
array(
1234 => array( 'id'=>1234, 'name'=>'myuser0', 'score'=>1 ),
1235 => array( 'id'=>1235, 'name'=>'myuser1', 'score'=>0 )
)
</pre>
Example 2:
<pre>
self::getCollectionFromDB( "SELECT player_id id, player_name name FROM player", true );

Result:
array(
1234 => 'myuser0',
1235 => 'myuser1'
)

</pre>

; getNonEmptyCollectionFromDB( $sql )
: Idem than previous one, but raise an exception if the collection is empty

; function getObjectFromDB( $sql )
: Returns one row for the sql SELECT query as an associative array or null if there is no result
: Raise an exception if the query return more than one row

Example:
<pre>
self::getObjectFromDB( "SELECT player_id id, player_name name, player_score score FROM player WHERE player_id='$player_id'" );

Result:
array(
'id'=>1234, 'name'=>'myuser0', 'score'=>1
)
</pre>

; getNonEmptyObjectFromDB( $sql )
: Idem than previous one, but raise an exception if no row is found

; getObjectListFromDB( $sql, $bUniqueValue=false )
: Return an array of rows for a sql SELECT query.
: the result if the same than "getCollectionFromDB" except that the result is a simple array (and not an associative array).
: The result can be empty.
: If you specified $bUniqueValue=true and if your SQL query request 1 field, the method returns directly an array of values.

Example 1:
<pre>
self::getObjectListFromDB( "SELECT player_id id, player_name name, player_score score FROM player" );

Result:
array(
array( 'id'=>1234, 'name'=>'myuser0', 'score'=>1 ),
array( 'id'=>1235, 'name'=>'myuser1', 'score'=>0 )
)
</pre>
Example 2:
<pre>
self::getObjectListFromDB( "SELECT player_id id, player_name name FROM player", true );

Result:
array(
'myuser0',
'myuser1'
)

</pre>

; getDoubleKeyCollectionFromDB( $sql, $bSingleValue=false )
: Return an associative array of associative array, from a SQL SELECT query.
: First array level correspond to first column specified in SQL query.
: Second array level correspond to second column specified in SQL query.
: If bSingleValue = true, keep only third column on result

; DbGetLastId()
: Return the PRIMARY key of the last inserted row (see PHP mysql_insert_id function).

; DbAffectedRow()
: Return the number of row affected by the last operation

; escapeStringForDB( $string )
: You must use this function on every string type data in your database that contains unsafe data.
: (unsafe = can be modified by a player).
: This method makes sure that no SQL injection will be done through the string used.

<pre>
self::getObjectFromDB( "SELECT player_id id, player_name name, player_color color FROM player WHERE player_id='1234'" );

Result:
array(
'id' => 1234,
'name' => 'myuser1',
'color' => 'ff0000'
)

</pre>

; function getNonEmptyObjectFromDB( $sql )
: Idem, but raise an exception if the query doesn't return exactly one row

Note: see Editing [[Game database model: dbmodel.sql]] to know how to define your database model.

== Use globals ==

Sometimes, you have to keep a single integer value that is global to your game, and you don't want to create a DB table specifically for it.

Using a BGA framework "global", you can do such a thing. Your value will be stored in the "global" table in database, and you can access it with simple methods.

'''initGameStateLabels'''

This method is located at the beginning of your game logic. This is the place you defines the globals used in your game logic, by assigning them IDs.

You can define up to 89 globals, with IDs from 10 to 89. You must NOT use globals outside this range as globals are used by other components of the framework.

<pre>
self::initGameStateLabels( array(
"my_first_global_variable" => 10,
"my_second_global_variable" => 11
) );
</pre>

'''setGameStateInitialValue( $value_label, $value_value )'''

Init your global value. Must be called before any use of your global, so you should call this method from your "setupNewGame" method.

'''getGameStateValue( $value_label )'''

Retrieve the current value of a global.

'''setGameStateValue( $value_label, $value_value )'''

Set the current value of a global.

'''incGameStateValue( $value_label, $increment )'''

Increment the current value of a global. If increment is negative, decrement the value of the global.

Return the final value of the global.

== Game states and active players ==

; checkAction( $actionName, $bThrowException=true )
: Check if action is valid regarding current game state (exception if fails)
: The action is valid if it is listed as a "possibleactions" in the current game state (see game state description).
: This method MUST be called in the first place in ALL your PHP methods that handle players action, in order to make sure a player can't do an action when the rules disallow it at this moment of the game.
: if "bThrowException" is set to "false", the function return false in case of failure instead of throwing and exception. This is useful when several actions are possible in order to test each of them without throwing exceptions.

; activeNextPlayer()
: Make the next player active in the natural player order.
: Note: you CANT use this method in a "activeplayer" or "multipleactiveplayer" state. You must use a "game" type game state for this.

; activePrevPlayer()
: Make the previous player active (in the natural player order).
: Note: you CANT use this method in a "activeplayer" or "multipleactiveplayer" state. You must use a "game" type game state for this.

; $this->gamestate->changeActivePlayer( $player_id )
: You can call this method to make any player active.
: Note: you CANT use this method in a "activeplayer" or "multipleactiveplayer" state. You must use a "game" type game state for this.

; $this->gamestate->getActivePlayerList()
: With this method you can retrieve the list of the active player at any time.
: During a "game" type gamestate, it will return a void array.
: During a "activeplayer" type gamestate, it will return an array with one value (the active player id).
: during a "multipleactiveplayer" type gamestate, it will return an array of the active players id.
: Note: you should only use this method is the latter case.

; $this->gamestate->setAllPlayersMultiactive()
: With this method, all playing players are made active.
: Usually, you use this method at the beginning (ex: "st" action method) of a multiplayer game state when all players have to do some action.

; $this->gamestate->setPlayersMultiactive( $players, $next_state )
: Make a specific list of players active during a multiactive gamestate.
: Bare in mind it doesn't deactivate other previously active players.
: "players" is the array of player id that should be made active.
: In case "players" is empty, the method trigger the "next_state" transition to go to the next game state.

; $this->gamestate->setPlayerNonMultiactive( $player_id, $next_state )
: During a multiactive game state, make the specified player inactive.
: Usually, you call this method during a multiactive game state after a player did his action.
: If this player was the last active player, the method trigger the "next_state" transition to go to the next game state.

; $this->gamestate->checkPossibleAction( $action )
: (rarely used)
: This works exactly like "checkAction", except that it do NOT check if current player is active.
: This is used specifically in certain game states when you want to authorize some additional actions for players that are not active at the moment.
: Example: in Libertalia game, you want to authorize players to change their mind about card played. They are of course not active at the time they change their mind, so you cannot use "checkAction" and use "checkPossibleAction" instead.

== Players turn order ==

'''getNextPlayerTable()'''

Return an associative array which associate each player with the next player around the table.

In addition, key 0 is associated to the first player to play.

Example: if three player with ID 1, 2 and 3 are around the table, in this order, the method returns:
<pre>
array(
1 => 2,
2 => 3,
3 => 1,
0 => 1
);
</pre>

'''getPrevPlayerTable()'''

Same as above, but the associative array associate the previous player around the table.

'''getPlayerAfter( $player_id )'''

Get player playing after given player in natural playing order.

'''getPlayerBefore( $player_id )'''

Get player playing before given player in natural playing order.

== Notify players ==

To understand notifications, please read [http://www.slideshare.net/boardgamearena/the-bga-framework-at-a-glance The BGA Framework at a glance] first.

'''IMPORTANT'''

Notifications are sent at the very end of the request, when it ends normally. It means that if you throw an exception for any reason (ex: move not allowed), no notifications will be sent to players.

'''notifyAllPlayers( $notification_type, $notification_log, $notification_args )'''

Send a notification to all players of the game.

* notification_type:
A string that defines the type of your notification.

Your game interface Javascript logic will use this to know what is the type of the received notification (and to trigger the corresponding method).

* notification_log:
A string that defines what is to be displayed in the game log.

You can use an empty string here (""). In this case, nothing is displayed in the game log.

If you define a real string here, you should use "clienttranslate" method to make sure it can be translate.

You can use arguments in your notification_log strings, that refers to values defines in the "notification_args" argument (see below).

Note: you CAN use some HTML inside your notification log, and it is working. However:
_ pay attention to keep the log clear.
_ try to not include some HTML tags inside the "clienttranslate" method, otherwise it will make the translators work more difficult. You can use a notification argument instead, and provide your HTML through this argument.

* notification_args:
The arguments of your notifications, as an associative array.

This array will be transmitted to the game interface logic, in order the game interface can be updated.

Complete notifyAllPlayers example (from "Reversi"):

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

You can see in the example above the use of the "clienttranslate" method, and the use of 2 arguments "player_name" and "returned_nbr" in the notification log.

Important: NO private date must be sent with this method, as a cheater could see it even it is not used explicitly by the game interface logic. If you want to send private information to a player, please use notifyPlayer below.

'''notifyPlayer( $player_id, $notification_type, $notification_log, $notification_args )'''

Same as above, except that the notification is sent to one player only.

This method must be used each time some private information must be transmitted to a player.

== Game statistics ==

There are 2 types of statistics:
* a "player" statistic is a statistic associated to a player
* a "table" statistics is a statistic not associated to a player (global statistic for this game).

See [[Game statistics: stats.inc.php]] to see how you defines statistics for your game.

'''initStat( $table_or_player, $name, $value, $player_id=null )'''
Create a statistic entry for the specified statistics with a default value.
This method must be called for each statistics of your game, in your setupNewGame method.

'table_or_player' must be set to "table" if this is a table statistics, or "player" if this is a player statistics.

'name' is the name of your statistics, as it has been defined in your stats.inc.php file.

'value' is the initial value of the statistics. If this is a player statistics and if the player is not specified by "player_id" argument, the value is set for ALL players.

'''function setStat( $value, $name, $player_id = null )'''

Set a statistic value.

If "player_id" is not specified, setStat consider it is a TABLE statistic.

If "player_id" is specified, setStat consider it is a PLAYER statistic.

'''incStat( $delta, $name, $player_id = null )'''

Increment (or decrement) specified statistic value. Same behavior as above.

== Translations ==

See [[Translations]]

== Manage player scores and Tie breaker ==

At the end of the game, players automatically get a rank depending on their score: the player with the biggest score is #1, the player with the second biggest score is #2, and so on...

During the game, you update player's score directly by updating "player_score" field of "player" table in database.

Examples:
<pre>

// +2 points to active player
self::DbQuery( "UPDATE player SET player_score=player_score+2 WHERE player_id='".self::getActivePlayerId()."'" );

// Set score of active player to 5
self::DbQuery( "UPDATE player SET player_score=5 WHERE player_id='".self::getActivePlayerId()."'" );

</pre>

Note: don't forget to notify the client side in order the score control can be updated accordingly.

'''Tie breaker'''

Tie breaker is used when two players get the same score at the end of a game.

Tie breaker is using "player_score_aux" field of "player" table. It is updated exactly like the "player_score" field.

Tie breaker score is displayed only for players who are tied at the end of the game. Most of the time, it is not supposed to be displayed explicitly during the game.

When you are using "player_score_aux" functionality, you must describe the formula to use in your Constructor method like this:

<pre>
$this->tie_breaker_description = self::_("Describe here your tie breaker formula");
</pre>

This description will be used as a tooltip to explain to players how this auxiliary score has been calculated.

== Reflexion time ==

; function giveExtraTime( $player_id, $specific_time=null )
: Give standard extra time to this player.
: Standard extra time depends on the speed of the game (small with "slow" game option, bigger with other options).
: You can also specify an exact time to add, in seconds, with the "specified_time" argument (rarely used).

== Managing errors and exceptions ==

Note: when you throw an exception, all database changes and all notifications are cancelled immediately. This way, the game situation that were existing before the request is completely restored.

; throw new BgaUserException ( $error_message)
: Base class to notify a user error
: You must throw this exception when a player want to do something that he is not allowed to do.
: The error message will be shown to the player as a "red message", so it must be translated.
: Throwing such an exception is NOT considered as a bug, so it is not traced in BGA error logs.

Example from Gomoku:
<pre>
throw new BgaUserException( self::_("There is already a stone on this intersection, you can't play there") );
</pre>

; throw new BgaSystemVisibleException ( $error_message)
: You must throw this exception when you detect something that is not supposed to happened into your code.
: The error message is shown to the user as an "Unexpected error", in order he can report it in the forum.
: The error message is logged in BGA error logs. If it happens regularly, we will report it to you.

; throw new BgaSystemException ( $error_message)
: Base class to notify a system exception. The message will be hidden from the user, but show in the logs. Use this if the message contains technical information.
: You shouldn't use this type of exception except if you think the information shown could be critical. Indeed: a generic error message will be shown to the user, so it's going to be difficult for you to see what happened.

== Zombie mode ==

When a player leaves a game for any reason (expelled, quit), he becomes a "zombie player". In this case, the results of the game won't count for statistics, but this is cool if the other players can finish the game anyway. That's why zombie mode exists: allow the other player to finish the game, even if the situation is not ideal.

While developing your zombie mode, keep in mind that:
* Do not refer to the rules, because this situation is not planned by the rules.
* Try to figure that you are playing with your friends and one of them has to leave: how can we finish the game without killing the spirit of the game?
* The idea is NOT to develop an artificial intelligence for the game.

Most of the time, the best thing to do when it is zombie player turn is to jump immediately to a state where he is not active anymore. For example, if he is in a game state where he has a choice between playing A and playing B, the best thing to do is NOT to choose A or B, but to pass. So, even if there's no "pass" action in the rules, add a "zombiepass" transitition in your game state and use it.

Each time a zombie player must play, your "zombieTurn" method is called.

Parameters:
* $state: the name of the current game state.
* $active_player: the id of the active player.

Most of the time, your zombieTurn method looks like this:

<pre>
function zombieTurn( $state, $active_player )
{
$statename = $state['name'];

if( $statename == 'myFirstGameState'
|| $statename == 'my2ndGameState'
|| $statename == 'my3rdGameState'
....
)
{
$this->gamestate->nextState( "zombiePass" );
}
else
throw new feException( "Zombie mode not supported at this game state: ".$statename );
}
</pre>

Note that in the example above, all corresponding game state should implement "zombiePass" as a transition.

Your game state machine: states.inc.php

2013-04-05T02:46:37Z

Pikiou: /* args */ returned value from the arg function must be an associative array

This file describes the game states machine of your game (all the game states properties, and the transitions to get from one state to another).

Important: to understand the game state machine, the best is to read this presentation first:

[http://www.slideshare.net/boardgamearena/bga-studio-focus-on-bga-game-state-machine Focus on BGA game state machine]

== Overall structure ==

The machine states is described by a PHP associative array.

Example:

<pre>
$machinestates = array(

// The initial state. Please do not modify.
1 => array(
"name" => "gameSetup",
"description" => clienttranslate("Game setup"),
"type" => "manager",
"action" => "stGameSetup",
"transitions" => array( "" => 2 )
),

// Note: ID=2 => your first state

2 => array(
"name" => "playerTurn",
"description" => clienttranslate('${actplayer} must play a card or pass'),
"descriptionmyturn" => clienttranslate('${you} must play a card or pass'),
"type" => "activeplayer",
"possibleactions" => array( "playCard", "pass" ),
"transitions" => array( "playCard" => 2, "pass" => 2 )
),
</pre>

== Syntax ==

=== id ===

The keys determine game states IDs (in the example above: 1 and 2).

IDs must be positive integers.

ID=1 is reserved for the first game state and should not be used (and you must not modify it).

ID=99 is reserved for the last game state of the game (end of the game) (and you must not modify it).

Note: you may use any ID, even ID greater than 100. But you cannot use 1 and 99.

Note²: You can't of course use the same ID twice.

=== name ===

(mandatory)

The name of a game state is used to identify it in your game logic.

Several game states can share the same name, however this is not recommended.

PHP example:
<pre>

// Get current game state
$state = $this->gamestate->state();
if( $state['name'] == 'myGameState' )
{
...
}

</pre>

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

switch( stateName )
case 'myGameState':

// Do some stuff at the beginning at this game state
....

break;
</pre>

=== type ===

(mandatory)

You can use 3 types of game states:
* activeplayer (1 player is active and must play)
* multipleactiveplayer (1..N players can be active and must play)
* game (no player is active. This is a transitional state to do something automatic specified by game rules)

=== description ===

(mandatory)

The description is the string that is displayed in the main action bar (top of the screen) when the state is active.

When a string is specified as a description, you must use "clienttranslate" in order the string can be translate on the client side:

<pre>
"description" => clienttranslate('${actplayer} must play a card or pass'),
</pre>

In the description string, you can use ${actplayer} to refer to the active player.

You can also use custom arguments in your description. These custom arguments correspond to values returned by your "args" PHP method (see below "args" field).

Example of custom field:
<pre>

In states.inc.php:
"description" => clienttranslate('${actplayer} must choose ${nbr} identical energies'),
"args" => "argMyArgumentMethod"

In mygame.game.php:
function argMyArgumentMethod()
{
return array(
'nbr' => 2 // In this case ${nbr} in the description will be replaced by "2"
);
}
</pre>

Note: You may specify an empty string ("") here if it never happens that the game remains in this state (ie: if this state immediately jump to another state when activated).

Note²: Usually, you specify a string for "activeplayer" and "multipleactiveplayer" game states, and you specify an empty string for "game" game states. BUT, if you are using synchronous notifications, the client can remains few seconds on a "game" type game state, and in this case this may be useful to display a description in the status bar during this state.

=== descriptionmyturn ===

(mandatory for "activeplayer" and "multipleactiveplayer" game states type)

"descriptionmyturn" has exactly the same role and properties than "description", except that this value is displayed to the current active player - or to all active players in case of a multipleactiveplayer game state.

In general, we have this situation:

<pre>
"description" => clienttranslate('${actplayer} can take some actions'),
"descriptionmyturn" => clienttranslate('${you} can take some actions'),
</pre>

Note: you can use ${you} in description my turn in order the description can display "You" instead of the name of the player.

=== action ===

(mandatory for "game" game state type)

"action" specify a PHP method to call when entering into this game state.

Example:
<pre>
In states.inc.php:
28 => array(
"name" => "startPlayerTurn",
"description" => '',
"type" => "game",
"action" => "stStartPlayerTurn",

In mygame.game.php:
function stStartPlayerTurn()
{
// ... do something at the beginning of this game state
</pre>

Usually, for "game" game state type, the action method is used to do some automatic stuff specified by the rules (ex: check victory conditions, deal cards for a new round, go to the next player...) and then jump to another game state.

Note: a BGA convention specify that PHP method called with "action" are prefixed by "st".

=== transitions ===

(mandatory)

With "transition" you specify in which game state you can jump from a given game state.

Example:
<pre>
25 => array(
"name" => "myGameState",
"transitions" => array( "nextPlayer" => 27, "endRound" => 39 ),
....
}
</pre>

In the example above, if "myGameState" is the current active game state, I can jump to game state with ID 27, or game state with ID 39.

Example to jump to ID 27:
<pre>
In mygame.game.php:
$this->gamestate->nextState( "nextPlayer" );
</pre>

Important: "nextPlayer" is the name of the transition, and NOT the name of the target game state. Several transitions can lead to the same game state.

Note: if you have only 1 transition, you may give it an empty name.

Example:
<pre>
In states.inc.php:
"transitions" => array( "" => 27 ),

In mygame.game.php:
$this->gamestate->nextState( ); // We don't need to specify a transition as there is only one here
</pre>

=== possibleactions ===

(mandatory for "activeplayer" and "multipleactiveplayer" game states)

"possibleactions" defines the actions possible by the players at this game state.

By defining "possibleactions", you make sure players can't do actions that they are not allowed to do at this game states.

Example:

<pre>
In states.game.php:
"possibleactions" => array( "playCard", "pass" ),

In mygame.game.php:
function playCard( ...)
{
self::checkAction( "playCard" ); // Will failed if "playCard" is not specified in "possibleactions" in current game state.

....

In mygame.js:
playCard: function( ... )
{
if( this.checkAction( "playCard" ) ) // Will failed if "playCard" is not specified in "possibleactions" in current game state.
{ return ; }

....

</pre>

=== args ===

(optional)

From time to time, it happens that you need some information on the client side (ie : for your game interface) only for a specific game state.

Example 1 : for Reversi, the list of possible moves during playerTurn state.
Example 2 : in Caylus, the number of remaining king's favor to choose in the state where the player is choosing a favor.
Example 3 : in Can't stop, the list of possible die combination to be displayed to the active player in order he can choose among them.

In such a situation, you can specify a method name as the « args » argument for your game state. This method must get some piece of information about the game (ex : for Reversi, the possible moves) and return them.

Thus, this data can be transmitted to the clients and used by the clients to display it. It should always be an associative array.

Let's see a complete example using args with « Reversi » game :

In states.inc.php, we specify some « args » argument for gamestate « playerTurn » :
<pre>
10 => array(
"name" => "playerTurn",
"description" => clienttranslate('${actplayer} must play a disc'),
"descriptionmyturn" => clienttranslate('${you} must play a disc'),
"type" => "activeplayer",
"args" => "argPlayerTurn", <================================== HERE
"possibleactions" => array( 'playDisc' ),
"transitions" => array( "playDisc" => 11, "zombiePass" => 11 )
),
</pre>

It corresponds to a « argPlaceWorkers » method in our PHP code (reversi.game.php):
<pre>
function argPlayerTurn()
{
return array(
'possibleMoves' => self::getPossibleMoves()
);
}
</pre>

Then, when we enter into « playerTurn » game state on the client side, we can highlight the possible moves on the board using information returned by argPlayerTurn :

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

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

Note: you can also used values returned by your "args" method to have some custom values in your "description"/"descriptionmyturn" (see above).

Note: as a BGA convention, PHP methods called with "args" are prefixed by "arg" (ex: argPlayerTurn).

=== updateGameProgression ===

(optional)

IF you specify "updateGameProgression => true" in a game state, your "getGameProgression" PHP method will be called at the beginning of this game state - and thus the game progression of the game will be updated.

At least one of your game state (any of them) must specify updateGameProgression=>true.

Game interface logic: yourgamename.js

2013-04-02T15:45:08Z

Pikiou: /* Tooltips */ addTooltip and addTooltipHtml get a node id, not a node element

This is the main file for your game interface. Here you will define:

* which actions on the page will generate calls to the server
* what happens when you get a notification for change from the server and how it will show in the browser.

== File structure ==

The details on how the file is structured is described directly with comments on the code skeleton provided to you.

Basically, here's this structure:
* constructor: here you can define variable global to your whole interface.
* setup: this method is called when the page is refreshed, in order you can setup the game interface.
* onEnteringState: the method is called when entering in a new game state. This way you can customize the view for this game state.
* onLeavingState: the method is called when leaving a game state.
* onUpdateActionButtons: called when entering in a new state, in order you can add action buttons in status bar.
* (utility methods): at this place you can define your utility methods
* (player's actions): at this place you can write your handlers for player's action on the interface (ex: click on an item).
* setupNotifications: in this method you associate notifications with notification handlers. This way, for each game notification, you trigger a javascript method to handle it and update the game interface.
* (notification handlers): at this place you can define your notifications handlers.

== General tips ==

; this.player_id
: Id of the player on whose browser the code is running.

; this.isSpectator
: Flag set to true if the user at the table is a spectator (not a player).
: Note: if you want to hide some element for spectators, you'd better use [[Game_interface_stylesheet:_yourgamename.css#spectatorMode|CSS 'spectatorMode' class]].

; this.gamedatas
: Contains your initial set of datas to init the game, created at game start or game refresh (F5)
: You can update it as needed to keep an up to date reference of the game on the client side if you need it (most of the time you don't).

; isCurrentPlayerActive()
: Returns true if the player on whose browser the code is running is currently active (it's his turn to play)

; this.getActivePlayerId()
: Return the ID of active player, or null if we are not in a "activeplayer" type state.

; this.getActivePlayers()
: Return an array with the IDs of players that are currently active (or an empty array if there is not).

== Dojo framework ==

BGA is using the [http://dojotoolkit.org/ Dojo Javascript framework].

The Dojo framework allows us to do complex things easier, and the BGA framework is using Dojo framework a lot.

To realize game although, you only need to use a few part of the Dojo framework. All the Dojo methods you need to use are describe on this page.

== Access and manipulate the DOM ==

'''$('some_html_element_id')'''

The $() function is used to get some HTML element using its "id" attribute.

Example 1: modify the content of a "span" element:
<pre>
In your HTML code:
<span id="a_value_in_the_game_interface">1234</span>

In your Javascript code:
$('a_value_in_the_game_interface').innerHTML = "9999";
</pre>

Note: $() is the standard method to access some HTML element with BGA Framework. You must not use "getElementById" function.

'''dojo.style'''

With dojo.style you can modify a CSS property of any HTML element of your interface.

Examples:
<pre>
// Make an element disappear
dojo.style( 'my_element', 'display', 'none' );

// Give an element a 2px border
dojo.style( 'my_element', 'borderWidth', '2px' );

// Change the background position of an element
// (very practical when you are using CSS sprite to transform an element to another)
dojo.style( 'my_element', 'backgroundPosition', '-20px -50px' );
</pre>

Note: you must always use dojo.style to modify CSS properties of HTML elements.

Note²: if you have to modify several CSS properties of an element, or if you have some complex CSS transformation to do, you should consider using dojo.addClass/dojo.removeClass (see below).

'''dojo CSS classes manipulation'''

In many situation, a bunch of many small CSS property update can be replaced by a CSS class change (ie: you add a CSS class to your element instead of applying all modification manually).

Advantages are:
* All your CSS stuff remains in your CSS file.
* You can add/remove a list of CSS modifications with a simple function and whithout error.
* You can test if you applied the stuff to an element with "dojo.hasClass" method.

Example from "Reversi":
<pre>
// We add "possibleMove" to an element
dojo.addClass( 'square_'+x+'_'+y, 'possibleMove' );

// In our CSS file, the class is defined as:
.possibleMove {
background-color: white;
opacity: 0.2;
filter:alpha(opacity=20); /* For IE8 and earlier */
cursor: pointer;
}

// So we've applied 4 CSS property change in one line of code.

// ... and when we need to check if a square is a possible move on client side:
if( dojo.hasClass( 'square_'+x+'_'+y, 'possibleMove' ) )
{ ... }

// ... and if we want to remove all possible moves in one line of code (see "dojo.query" method):
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );
</pre>

Conclusion: we encourage you to use dojo.addClass, dojo.removeClass and dojo.hasClass to make your life easier :)

'''dojo.query'''

With dojo.query, you can query a bunch of HTML elements with a single function, with a "CSS selector" style.

Example:
<pre>
// All elements with class "possibleMove":
var elements = dojo.query( '.possibleMove' );

// Count number of tokens (ie: elements with class "token") on the board (ie: element with id "board"):
dojo.query( '#board .token' ).length;
</pre>

But what is really cool with dojo.query is that you can combine it with almost all methods above.

Examples:
<pre>
// Trigger a method when the mouse enter in any element with class "meeple":
dojo.query( '.meeple' ).connect( 'onmouseenter', this, 'myMethodToTrigger' );

// Hide all meeples who are on the board
dojo.query( '#board .meeple' ).style( 'display', 'none' );
</pre>

'''dojo.place'''

dojo.place is the best function to insert some HTML code somewhere in your game interface without breaking something. It is much better to use that "innerHTML=''" method as soon as you must insert HTML tags and not only values.

<pre>
// Insert your HTML code as a child of a container element
dojo.place( "<your html code>", "your_container_element_id" );

// Replace the container element with your new html
dojo.place( "<your html code>", "your_container_element_id", "replace" );

</pre>

Note: the third parameter of dojo.place can take various interesting value: "first", "after", ... [http://dojotoolkit.org/reference-guide/1.7/dojo/place.html See full doc on dojo.place].

Usually, when you want to insert some piece of HTML in your game interface, you should use "[[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl#Javascript_templates|Javascript templates]]".

'''addStyleToClass: function( cssClassName, cssProperty, propertyValue )'''

Same as dojo.style(), but for all the nodes set with the specified cssClassName

=== Animations ===

'''this.slideToObject( mobile_obj, target_obj, duration, delay )'''

You can use slideToObject to "slide" an element to a target position.

Sliding element on the game area is the recommended and the most used way to animate your game interface. Using slides allow players to figure out what is happening on the game, as if they were playing with the real boardgame.

The parameters are:
* mobile_obj: the ID of the object to move. This object must be "relative" or "absolute" positioned.
* target_obj: the ID of the target object. This object must be "relative" or "absolute" positioned. Note that it is not mandatory that mobile_obj and target_obj have the same size. If their size are different, the system slides the center of mobile_obj to the center of target_obj.
* duration: (optional) defines the duration in millisecond of the slide. The default is 500 milliseconds.
* delay: (optional). If you defines a delay, the slide will start only after this delay. This is particularly useful when you want to slide several object from the same position to the same position: you can give a 0ms delay to the first object, a 100ms delay to the second one, a 200ms delay to the third one, ... this way they won't be superposed during the slide.

BE CAREFUL: The method returns an dojo.fx animation, so you can combine it with other animation if you want to. It means that you have to call the "play()" method, otherwise the animation WON'T START.

Example:
<pre>
this.slideToObject( "some_token", "some_place_on_board" ).play();
</pre>

'''this.slideToObjectPos( mobile_obj, target_obj, target_x, target_y, duration, delay )'''

This method does exactly the same than "slideToObjectPos", except than you can specify some (x,y) coordinates. This way, "mobile_obj" will slide to the specified x,y position relatively to "target_obj".

Example: slide a token to some place on the board, 10 pixels to the bottom:
<pre>
this.slideToObjectPos( "some_token", "some_place_on_board", 0, 10 ).play();
</pre>

'''this.slideTemporaryObject( mobile_obj_html, mobile_obj_parent, from, to, duration, delay )'''

This method is useful when you want to slide a temporary HTML object from one place to another. As this object does not exists before the animation and won't remain after, it could be complex to create this object (with dojo.place), to place it at its origin (with placeOnObject) to slide it (with slideToObject) and to make it disappear at the end.

slideTemporaryObject does all of this for you:
* mobile_obj_html is a piece of HTML code that represent the object to slide.
* mobile_obj_parent is the ID of an HTML element of your interface that will be the parent of this temporary HTML object.
* from is the ID of the origin of the slide.
* to is the ID of the target of the slide.
* duration/delay works exactly like in "slideToObject"

Example:
<pre>
this.slideTemporaryObject( '<div class="token_icon"></div>', 'tokens', 'my_origin_div', 'my_target_div' );
</pre>

'''this.fadeOutAndDestroy( node )'''

This function fade out the target HTML node, then destroy it.

Example:
<pre>
this.fadeOutAndDestroy( "a_card_that_must_disappear" );
</pre>

CAREFUL: the HTML node still exists until during few milliseconds, until the fadeOut has been completed.

=== Moving elements ===

'''this.placeOnObject( mobile_obj, target_obj )'''

placeOnObject works exactly like "slideToObject", except that the effect is immediate.

This is not really an animation, but placeOnObject is frequently used before starting an animation.

Example:
<pre>
// (We just created an object "my_new_token")

// Place the new token on current player board
this.placeOnObject( "my_new_token", "overall_player_board_"+this.player_id );

// Then slide it to its position on the board
this.slideToObject( "my_new_token", "a_place_on_board" ).play();
</pre>

'''this.placeOnObjectPos( mobile_obj, target_obj, target_x, target_y )'''

This method works exactly like placeOnObject, except than you can specify some (x,y) coordinates. This way, "mobile_obj" will be placed to the specified x,y position relatively to "target_obj".

'''this.attachToNewParent( mobile_obj, target_obj )'''

With this method, you change the HTML parent of "mobile_obj" element. "target_obj" is the new parent of this element. The beauty of
attachToNewParent is that the mobile_obj element DOES NOT MOVE during this process.

Note: what happens is that the method calculate a relative position of mobile_obj to make sure it does not move after the HTML parent changes.

Why using this method?

Changing the HTML parent of an element can be useful for the following reasons:
* When the HTML parent moves, all its child are moving with them. If some game elements is no more linked with a parent HTML object, you may want to attach it to another place.
* The z_order (vertical order of display) depends on the position in the DOM, so you may need to change the parent of some game elements when they are moving in your game area.

CAREFUL: when you attach an HTML element with a new parent, you break all references to this HTML element (ex: dojo.connect).

== Players input ==

'''dojo.connect'''

Used to associate a player event with one of your notification method.

Example: associate a click on an element ("my_element") with one of our method ("onClickOnMyElement"):
<pre>
dojo.connect( $('my_element'), 'onClick', this, 'onClickOnMyElement' );
</pre>

Note: this is the only possible correct way to associate a player input event to your code, and you must not use anything else.

'''this.checkAction( "my_action_name" )'''

Usage: checkAction: function( action, nomessage )

Check if player can do the specified action by taking into account:
* current game state
* interface locking (a player can't do any action if an action is already in progress)

return true if action is authorized (ie: the action is listed as a "possibleaction" in current game state).

return false and display an error message if not (display no message if nomessage parameter is true). The displayed error message could be either "This move is not allowed at this moment" or "An action is already in progress".

Example:
<pre>
function onClickOnGameElement( evt )
{
if( this.checkAction( "my_action" ) )
{
// Do the action
}
}
</pre>

'''this.ajaxcall( url, parameters, obj_callback, callback, callback_error )'''

This method must be used to send a player input to the game server.

* url: the url of the action to perform. For a game, it must be: "/<mygame>/<mygame>/myAction.html"
* parameters: an array of parameter to send to the game server. Note that "lock:true" must always be specified in this list of parameter in order the interface can be locked during the server call.
* obj_callback: must be set to "this".
* callback: a function to trigger when the server returns and everything went fine.
* callback_error: (optional and rarely used) a function to trigger when the server returns an error.

Usage:
<pre>
this.ajaxcall( '/mygame/mygame/myaction.html', { lock: true,
arg1: myarg1,
arg2: myarg2,
...
}, this, function( result ) {
// Do some stuff after a successful call
} );
</pre>

'''this.confirmationDialog()'''

Display a confirmation dialog with a yes/no choice.

We advice you to NOT use this function unless the player action is really critical and could ruins the game, because it slows down the game and upset players.

Usage: this.confirmationDialog( "Question to displayed", callback_function_if_click_on_yes );

Example:
<pre>
this.confirmationDialog( _('Are you sure to use this bonus (points penalty at the end of the game) ?'),
dojo.hitch( this, function() {
this.ajaxcall( '/seasons/seasons/useBonus.html',
{ id:bonus_id, lock:true }, this, function( result ) {} );
} ) );
</pre>

; addEventToClass: function( cssClassName, eventName, functionName )
: Same as dojo.connect(), but for all the nodes set with the specified cssClassName

'''this.addActionButton( id, label, method, (opt)depreciated, (opt)bHighlight )'''

You can use this method to add an action button in the main action status bar.

Arguments:
* id: a ID that should be unique in your HTML DOM document.
* label: the text of the button. Should be translatable (use _() function).
* method: the name of your method that must be triggered when the player clicks on this button.
* depreciated (optional): do not use this. Please not specify this argument or use "null".
* bHighlight: if set to "true", the button is going blink to catch player's attention. Please don't abuse of blinking button.

You should only use this method in your "onUpdateActionButtons" method. Usually, you use it like this (from Hears example):

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

if( this.isCurrentPlayerActive() )
{
switch( stateName )
{
case 'giveCards':
this.addActionButton( 'giveCards_button', _('Give selected cards'), 'onGiveCards' );
break;

}
}
},
</pre>

In the example above, we are adding a "Give selected cards" button in the case we are on game state "giveCards". When player clicks on this button, it triggers our "onGiveCards" method.

== Translations ==

See [[Translations]]

== Notifications ==

When something happens on the server side, your game interface Javascript logic received a notification.

Here's how you can handle these notifications on the client side.

=== Subscribe to notifications ===

Your Javascript "setupNotifications" method is the place where you can subscribe to notifications from your PHP code.

Here's how you associate one of your Javascript method to a notification "playDisc" (from Reversi example):

<pre>
// In setupNotifications method:
dojo.subscribe( 'playDisc', this, "notif_playDisc" );
</pre>

Note: the "playDisc" corresponds to the name of the notification you define it in your PHP code, in your "notifyAllPlayers" or "notifyPlayer" method.

Then, you have to define your "notif_playDisc" method:

<pre>
notif_playDisc: function( notif )
{
// Remove current possible moves (makes the board more clear)
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );

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

In a notification handler like our "notif_playDisc" method, you can access to all notifications arguments with "notif.args".

Example:
<pre>
// If you did this on PHP side:
self::notifyAllPlayers( "myNotification", '', array( "myArgument" => 3 ) );

// On Javascript side, you can access the "myArgument" like this:
notif_myNotification: function( notif )
{
alert( "myArgument = " + notif.args.myArgument );
}
</pre>

=== Synchronous notifications ===

When several notifications are received by your game interface, these notifications are processed immediately, one after the other, in the same exact order they have been generated in your PHP game logic.

However, sometimes, you need to give some time to the players to figure out what happened on the game before jumping to the next notification. Indeed, in many games, they are a lot of automatic actions, and the computer is going to resolve all these actions very fast if you don't tell it not to do so.

As an example, for Reversi, when someone is playing a disc, we want to wait 500 milliseconds before doing anything else in order the opponent player can figure out what move has been played.

Here's how we do this, right after our subscription:
<pre>
dojo.subscribe( 'playDisc', this, "notif_playDisc" );
this.notifqueue.setSynchronous( 'playDisc', 500 ); // Wait 500 milliseconds after executing the playDisc handler
</pre>

== Tooltips ==

'''this.addTooltip( nodeId, _( helpString ), _( actionString ), delay )'''

Add a simple text tooltip to the DOM node.

Specify 'helpString' to display some information about "what is this game element?".
Specify 'actionString' to display some information about "what happens when I click on this element?".

You must specify both helpString and actionString. Most of the time, you use only one and specify a void string ("") for the other one.

Usually, _() must be used for the text to be marked for translation.

"Delay" is an optional parameter. Usually, it is primarily used to specify a zero delay for some game element when the tooltip gives really important information for the game - but remember: no essential information must be placed in tooltips as they won't be displayed in some browser (see Guidelines).

Example:
<pre>
this.addTooltip( 'cardcount', _('Number of cards in hand'), '' );
</pre>

'''this.addTooltipHtml( nodeId, html, delay )'''

Add an HTML tooltip to the DOM node (for more elaborate content such as presenting a bigger version of a card).

'''this.addTooltipToClass( cssClass, _( helpString ), _( actionString ), delay )'''

Add a simple text tooltip to all the DOM nodes set with this cssClass.

IMPORTANT: all concerned nodes must have IDs to get tooltips.

'''addTooltipHtmlToClass( cssClass, html, delay )'''

Add an HTML tooltip to to all the DOM nodes set with this cssClass (for more elaborate content such as presenting a bigger version of a card).

IMPORTANT: all concerned nodes must have IDs to get tooltips

== Dialogs, warning messages, confirmation dialogs, ... ==

=== Warning messages ===

Sometimes, there is something important that is happening on the game and you have to make sure all players get the message. Most of the time, the evolution of the game situation or the game log is enough, but sometimes you need something more visible.

Ex: someone fulfill one of the end of the game condition, so this is the last turn.

'''this.showMessage( msg, type )'''

showMessage shows a message in a big rectangular area on the top of the screen of current player.

* "msg" is the string to display. It should be translated.
* "type" can be set to "info" or "error". If set to "info", the message will be an informative message on a white background. If set to "error", the message will be an error message on a red background.

Important: the normal way to inform players about the progression of the game is the game log. "showMessage" is intrusive and should not be used often.

=== Confirmation dialog ===

When an important action with a lot of consequences is triggered by the player, you may want to propose a confirmation dialog.

CAREFUL: the general guidelines of BGA is to AVOID the use of confirmation dialog. Confirmation dialogs slow down the game and bother players. The players knows that they have to pay attention about each move when they are playing online.

The situation where you should use a confirmation dialog are the following:
* It must not happen very often during a game.
* It must be linked to an action that can really "kill a game" if the player do not pay attention.
* It must be something that can be done by mistake (ex: a link on the action status bar).

How to display a confirmation dialog:
<pre>
this.confirmationDialog( _('Are you sure you want to make this?'), dojo.hitch( this, function() {
this.ajaxcall( '/mygame/mygame/makeThis.html', { lock:true }, this, function( result ) {} );
} ) );
</pre>

=== Dialogs ===

At first, you shouldn't use dialogs windows.

BGA guidelines specify that all game elements should be displayed on the main screen. Players can eventually scroll down to see game elements they don't need to see anytime, and you may eventually create anchors to move between game area section. Of course dialogs windows are very practical, but the thing is: all players know how to scroll down, and not all players know how to show up your dialog window. In addition, when the dialog shows up, players can't access the other game components.

Sometimes although, you need to display a dialog window. Here is how you do this:

<pre>

// Create the new dialog. You should store the handler in a member variable to access it later
this.myDlg = new dijit.Dialog({ title: _("my dialog title to translate") });

// Create the HTML of my dialog. The best practice here is to use [[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl#Javascript_templates|Javascript templates]]:
var html = this.format_block( 'jstpl_myDialogTemplate', {
arg1: myArg1,
arg2: myArg2,
...
} );

// Show the dialog
this.myDlg.attr("content", html );
this.myDlg.show();

// Now that the dialog has been displayed, you can connect your method to some dialog elements
// Example, a "close" button:
dojo.connect( $('closeDlg'), 'onclick', this, function(evt){
evt.preventDefault();
this.myDlg.hide();
} );

</pre>

Tip: be careful with "hide()" method to close your dialog: the dialog and its content is not completely removed from the DOM. It can cause you problems if you try to display the same dialog several times. A good practice is to wrap all the content of your dialog in a "<div id='myDlgContent'>" div element, and to call "dojo.destroy('myDlgContent')" before displaying your dialog.

=== Scoring dialogs ===

Sometimes at the end of a round you want to display a big table that details the points wins in each section of the game.

Example: in Hearts game, we display at the end of each round the number of "heart" cards collected by each player, the player who collected the Queen of Spades, and the total number of points loose by each player.

Scoring dialogs are managed entirely on '''PHP side''', but they are described here as their effects are visible only on client side.

Displaying a scoring dialog is quite simple and is using a special notification type: "tableWindow":
<pre>
// on PHP side:
$this->notifyAllPlayers( "tableWindow", '', array(
"id" => 'finalScoring',
"title" => clienttranslate("Title of the scoring dialog"),
"table" => $table
) );
</pre>

The "table" argument is a 2 dimensional PHP array that describe the table you want to display, line by line and column by column.

Example: display an 3x3 array of strings
<pre>
$table = array(
array( "one", "two", "three" ), // This is my first line
array( "four", "five", "six" ), // This is my second line
array( "seven", "height", "nine" ) // This is my third line
);
</pre>

As you can see above, in each "cell" of your array you can display a simple string value. But you can also display a complex value with a template and associated arguments like this:
<pre>
$table = array(
array( "one", "two", array( "str" => "a string with an ${argument}", "args" => array( 'argument' => 'argument_value' ) ) ),
array( "four", "five", "six" ),
array( "seven", "height", "nine" )
);
</pre>

This is especially useful when you want to display player names with colors. Example from "Hearts":
<pre>
$firstRow = array( '' );
foreach( $players as $player_id => $player )
{
$firstRow[] = array( 'str' => '${player_name}',
'args' => array( 'player_name' => $player['player_name'] ),
'type' => 'header'
);
}
$table[] = $firstRow;
</pre>

== Update players score ==

Increase a player score (with a positive or negative number):

<pre>
this.scoreCtrl[ player_id ].incValue( score_delta );
</pre>

Set a player score to a specific value:

<pre>
this.scoreCtrl[ player_id ].setValue( new_score );
</pre>

== Players panels ==

=== Adding stuff to player's panel ===

At first, create a new "JS template" string in your template (tpl) file:

(from Reversi example)
<pre>
var jstpl_player_board = '\<div class="cp_board">\
<div id="stoneicon_p${id}" class="gmk_stoneicon gmk_stoneicon_${color}"></div><span id="stonecount_p${id}">0</span>\
</div>';
</pre>

Then, you add this piece of code in your JS file to add this template to each player panel:

<pre>
// Setting up player boards
for( var player_id in gamedatas.players )
{
var player = gamedatas.players[player_id];

// Setting up players boards if needed
var player_board_div = $('player_board_'+player_id);
dojo.place( this.format_block('jstpl_player_board', player ), player_board_div );
}
</pre>

(Note: the code above is of course from your "setup" function in your Javascript).

Very often, you have to distinguish current player and others players. In this case, you just have to create another JS template (ex: jstpl_otherplayer_board) and use it when "player_id" is different than "this.player_id".

=== Player's panel disabling/enabling ===

'''this.disablePlayerPanel( player_id )'''

Disable given player panel (the panel background become gray).

Usually, this is used to signal that this played passes, or will be inactive during a while.

Note that the only effect of this is visual. There are no consequences on the behaviour of the panel itself.

'''this.enablePlayerPanel( player_id )'''

Enable a player panel that has been disabled before.

'''this.enableAllPlayerPanels()'''

Enable all player panels that has been disabled before.

== Image loading ==

See also [[Game_art:_img_directory]].

'''Be careful''': by default, ALL images of your img directory are loaded on a player's browser when he loads the game. For this reason, don't let in your img directory images that are not useful, otherwise it's going to slowdown the game load.

'''dontPreloadImage( image_file_name )'''

Using dontPreloadImage, you tell the interface to not preload a specific image in your img directory.

Example of use:
<pre>
this.dontPreloadImage( 'cards.png' );
</pre>

This is particularly useful if for example you have 2 different themes for a game. To accelerate the loading of the game, you can specify to not preload images corresponding to the other theme.

Another example of use: in "Gosu" game with Kamakor extension, you play with 5 sets of cards among 10 available. Cards images are organized by sets, and we only preload the images corresponding to the 5 current sets.

== Other useful stuff ==

'''dojo.hitch'''

With dojo.hitch, you can create a callback function that will run with your game object context whatever happen.

Typical example: display a BGA confirmation dialog with a callback function created with dojo.hitch:

<pre>
this.confirmationDialog( _('Are you sure you want to make this?'), dojo.hitch( this, function() {
this.ajaxcall( '/mygame/mygame/makeThis.html', { lock:true }, this, function( result ) {} );
} ) );
</pre>

In the example above, using dojo.hitch, we are sure that the "this" object will be set when the callback is called.

; updateCounters(counters)
: Useful for updating game counters in the player panel (such as resources).
: 'counters' arg is an associative array [counter_name_value => [ 'counter_name' => counter_name_value, 'counter_value' => counter_value_value], ... ]
: All counters must be referenced in this.gamedatas.counters and will be updated.
: DOM objects referenced by 'counter_name' will have their innerHTML updated with 'counter_value'.

== BGA GUI components ==

BGA framework provides some useful ready-to-use components for the game interface:

[[Studio#BGA_Studio_game_components_reference]]

Note that each time you are using an additional component, you must declare it at the top of your Javascript file in the list of modules used.

Example if you are using "ebg.stock":
<pre>
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/stock" /// <=== we are using ebg.stock module
],
</pre>

Stock

2013-01-26T04:58:23Z

Pikiou: /* Complete stock component reference */

"Stock" is a javascript component that you can use on your game interface to display a set of elements of the same size that need to be arranged in one or several lines.

Stock is very flexible and is the most used component in BGA games.

Stock is used for example:
* To display set of cards, typically hands (ex: in Hearts, Seasons, The Boss, Race for the Galaxy, ...).
* To display items in player panels (ex: Takenoko, Amyitis, ...)
* ... in many other situations. For example, black dice and cubes on cards in Troyes are displayed with stock components.

Using stock:
* Your items are arranged nicely and sorted by type.
* When adding (or removing) items to the set. All items slide smoothly to their new position in the set to host the new one.
* Select/unselect items is a built-in functionnality.
* You don't have to care about inserting/removing HTML piece of code: the entire life of the stock is managed by the component.

== Using stock: a simple example ==

Let's have a look on how the stock is used in game "Hearts" to display a hand of standard cards.

The stock is initialized in Javascript "setup" method like this:
<pre>
// Player hand
this.playerHand = new ebg.stock();
this.playerHand.create( this, $('myhand'), this.cardwidth, this.cardheight );
</pre>

Explanations:
* We create a new stock object for the player hand.
* As parameters of the "create" method, we provide the width/height of an item (=a card), and the container div "myhand" - which is a simple void "div" element defines in our HTML template (.tpl).

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

Here's how we tell stock what are the items type to display:
<pre>
// Explain there are 13 images per row in the CSS sprite image
this.playerHand.image_items_per_row = 13;

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

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

Note: in this specific example we need to generate a unique ID for each type of card based on its color and value. This is the only purpose of "getCardUniqueId".

From now, if we need to add - for example - the 5 of Heart to player's hand, we can do this.
this.playerHand.addToStock( this.getCardUniqueId( 2 /* 2=hearts */, 5 ) );

In reality, cards have some IDs, which are useful to manipulate them. This is the reason we are using "addToStockWithId" instead:
this.playerHand.addToStock( this.getCardUniqueId( 2 /* 2=hearts */, 5 ), my_card_id );

If afterwards we want to remove this card from the stock:
this.playerHand.removeFromStockById( my_card_id );

== Complete stock component reference ==

'''create( page, container_div, item_width, item_height ):'''

With create, you create a new stock component.
Parameters:
* page: the container page. Usually: "this".
* container_div: the container "<div>" element (a void <div> element in your template, with an id).
* a stock item width and height, in pixels.

(See "Hearts" example above).

'''count():'''

Return the total number of items in the stock right now.

'''addItemType( type, weight, image, image_position ):'''

Define a new type of item to the stock.

This is mandatory to define a new item type before adding it to the stock. Example: if you want to have a stock control that can contains cubes of 3 different colors, you must add 3 item types (one for each color).

Parameters:
_ type: ID of the type to add. You can choose any positive integer. All item types must have distinct IDs.
_ weight: weight of items of this type. Weight value is used to sort items of the stock during the display. Note that you can specify the same weight for all items (in this case they are not sorted).
_ image: URL of item image. Most of the time, you will use a CSS sprite for stock item, so you have to specify CSS sprite image here.
Be careful: you must specify the image url as this:
<pre>
g_themeurl+'img/your_game_name/yourimage.png'
</pre>
_ image_position: if "image" specify the URL of a CSS sprite, you must specify the position of the item image in this CSS sprite. For example, if you have a CSS sprite with 3 cubes with a size of 20x20 pixels each (so your CSS image has for example a size of 20x60 or 60x20), you specify "0" for the first cube image, 1 for the second, 2 for the third.
Important: there are more than one line of items in your CSS sprite, you must specify how many items per line you have in your CSS sprite like this:
<pre>
// Specify that there is 10 image items per row in images used in "myStockObject" control.
this.myStockObject.image_items_per_row = 10;
</pre>

'''addToStock( type, from )'''

Add an item to the stock, with the specified type.

To make your life easy, in most of the case we suggest you to use "addToStockWithId" in order to give an ID to the item added. "addToStock" is perfect when you are using a stock controls with items that are generic game material that does not need to be addressed individually (ex: a bunch of money tokens).

Parameters:
* type: ID of the item type to use (as specified in "addItemType")
* from: OPTIONNAL: if you specify a HTML item here, the item will appear on this item and will be slided to its position on the stock item.

Example:
<pre>
// Add a money token to the "player money" stock.
// The money token will appear on "player_id" player panel and will move to its position.
this.playerMoney.addToStock( MONEY_TOKEN, 'overall_player_board_'+player_id );
</pre>

Important: for a given stock control, you must use either addToStock or addToStockWithId, but NEVER BOTH OF THEM.

'''addToStockWithId( type, id, from )'''

This is exactly the same method than "addToStock", except that you associate an ID to the newly created item.

This is especially useful:
* When you need to know which item(s) has been selected by the user (see "getSelectedItems").
* When you need to remove a specific item from the stock with "removeFromStockById"

Important: for a given stock control, you must use either addToStock or addToStockWithId, but NEVER BOTH OF THEM.

'''removeFromStock( type, to )'''

Remove an item of the specific type from the stock.

"to" is an optional parameter. If "to" contains the ID of an HTML element, the item removed from the stock is slided to this HTML element before it disappear.

'''removeFromStockById( id, to )'''

Remove an item with a specific ID from the stock.

"to" is an optional parameter. If "to" contains the ID of an HTML element, the item removed from the stock is slided to this HTML element before it disappear.

'''removeAll()'''

Remove all items from the stock.

'''getPresentTypeList()'''

Return an array with all the types of items present in the stock right now.

Example:
<pre>
this.myStockControl.removeAll();
this.myStockControl.addToStock( 65 );
this.myStockControl.addToStock( 34 );
this.myStockControl.addToStock( 89 );
this.myStockControl.addToStock( 65 );

// The following returns: { 34:1, 65:1, 89:1 }
var item_types = this.myStockControl.getPresentTypeList();
</pre>

'''resetItemsPosition()'''

If you moved an item from the stock control manually (ex: after a drag'n'drop) and want to reset their position to their original ones, you can call this method.

'''changeItemsWeight( newWeights )'''

With this method you can change dynamically the weight of the item types in a stock control.

Items are immediately re-sorted with the new weight.

Example: with a stock control that contains classic cards, you can order them by value or by color. Using changeItemsWeight you can switch from one sort method to another when a player request this.

newWeights is an associative array: item type id => new weight.

Example:
<pre>
// Item type 1 gets a new weight of 10, 2 a new weight of 20, 3 a new weight of 30.
this.myStockControl.changeItemsWeight( { 1: 10, 2: 20, 3: 30 } );
</pre>

'''setSelectionMode( mode )'''

For each stock control, you can specify a selection mode:
* 0: no item can be selected by the player.
* 1: a maximum of one item can be selected by the player at the same time.
* 2: several items can be selected by the player at the same time.

'''isSelected( id )'''

Return true/false wether the specified item id has been selected or not.

'''selectItem( id )'''

Select the specified item.

'''unselectItem( id )'''

Unselect the specified item.

'''unselectAll()'''

Unselect all items of the stock.

'''onChangeSelection'''

This callback method is called when the player select/unselect an item of the stock.

You can connect this to one of your method like this:
<pre>
dojo.connect( this.myStockControl, 'onChangeSelection', this, 'onMyMethodToCall' );

(...)

onMyMethodToCall: function( control_name )
{
// This method is called when myStockControl selected items changed
var items = this.myStockControl.getSelectedItems();

// (do something)
},
</pre>

'''getSelectedItems()'''

Return the list of selected items, as an array with the following format:
<pre>
[
{ type:1, id: 1001 },
{ type:1, id: 1002 },
{ type:3, id: 1003 }
...
]
</pre>

'''getUnselectedItems()'''

Same as the previous one, but return unselected item instead of seleted ones.

'''getAllItems()'''

Get all items (same format than getSelectedItems and getUnselectedItems).

'''setOverlap( horizontal_percent, vertical_percent )'''

Make items on the stock control "overlap" on each other, to save space.

By default, horizontal_overlap and vertical_overlap are 0.

When horizontal_overlap=20, it means that a stock item must overlap on 20% of the width of the previous item. horizontal_overlap can't be over 100.

vertical_overlap works differently: one items on two are shifted up.

See "Jaipur" game to see an example to use of this function.

Main game logic: yourgamename.game.php

2013-01-10T16:57:45Z

Pikiou: /* Accessing player informations */ alternative for getPlayersNumber in setupNewGame

Tutorial reversi

2012-12-06T16:33:49Z

Pikiou: /* Make the move appears automatically */ Typos

== Introduction ==

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

Before you read this tutorial, you must:
* Read the overall presentations of the BGA Framework ([[Studio|see here]]).
* Know the [http://en.wikipedia.org/wiki/Reversi#Rules rules of Reversi].
* Know the languages used on BGA: PHP, SQL, HTML, CSS, Javascript.

== Create your first game ==

With the initial skeleton of code provided initially, you can already start a game from the BGA Studio. For now, we are going to work with 1 player only. Most of the time 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.

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

== Let it look like Reversi ==

It's always a good idea to start with a little bit of graphic work. Why? Because this helps to figure out how the final game will be, and issues that may appear later.

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

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

[[File:Board.jpg]]

Note that we are using a jpg file. Jpg are lighter than png, so faster to load. Later we are going to use PNGs for discs for transparency purpose.

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

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

* edit your reversi.css file to transform it into a visible board:

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

Refresh your page. Here's your board:

[[File:reversi1.jpg]]

== Make the squares appears ==

Now, what we need is to create some invisible HTML elements where squares are. These elements will be used as position references for width and black discs.
Obviously, we need 64 squares. To avoid writing 64 'div' elements on our template, we are going to use the "block" feature.

Let's modify our template like this:

<pre>
<div id="board">

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

</div>
</pre>

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.

Let's do it in our "reversi.view.php" file:

<pre>
$this->page->begin_block( "reversi_reversi", "square" );

$hor_scale = 64.8;
$ver_scale = 64.4;
for( $x=1; $x<=8; $x++ )
{
for( $y=1; $y<=8; $y++ )
{
$this->page->insert_block( "square", array(
'X' => $x,
'Y' => $y,
'LEFT' => round( ($x-1)*$hor_scale+10 ),
'TOP' => round( ($y-1)*$ver_scale+7 )
) );
}
}
</pre>

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.

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

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

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

Explanations:
* With "position: relative" on board, we ensure square elements are positioned relatively to board.
* 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.

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

[[File:reversi2.jpg]]

== The discs ==

Now, our board is ready to receive some disc tokens!

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

<pre>


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

Then, let's introduce a new piece of art with the discs. We need some transparency here so we are using a png file:

[[File:tokens.png]]

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].

Now, let's separate the disc with some CSS stuff:

<pre>
.token {
width: 56px;
height: 56px;
position: absolute;
background-image: url('../../img/reversi/tokens.png');
}
.tokencolor_ffffff { background-position: 0px 0px; }
.tokencolor_000000 { background-position: -56px 0px; }
</pre>

With this CSS code, we apply the classes "token" and "tokencolor_ffffff" to a div element and we've got a white token. Yeah.

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

Now, let's make a first token appear on our board. Disc tokens are not visible at the beginning of the game: they appear dynamically during the game. For this reason, we are going to make them appear from our Javascript code, with a BGA Framework technique called "JS template".

In our template file (reversi_reversi.tpl), let's create the piece of HTML needed to display our token:

<pre>
<script type="text/javascript">

// Templates

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

</script>
</pre>

Note: we already created the "templates" section for you in the game skeleton.

As you can see, we defined a JS template named "jstpl_token" with a piece of HTML and two variables: the color of the token and its x/y coordinates. Note that the syntax of the argument is different for template block variables (brackets) and JS template variables (dollar and brackets).

Now, let's create a method in our Javascript code that will make a token appear on the board, using this template:

<pre>
addTokenOnBoard: function( x, y, player )
{
dojo.place( this.format_block( 'jstpl_token', {
x_y: x+'_'+y,
color: this.gamedatas.players[ player ].color
} ) , 'tokens' );

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

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.

Then, with BGA "this.placeOnObject" method, we place this element over the panel of some player. Immediately after, using BGA "this.slidetoObject" method, we make the disc slide to the "square" element, its final destination.

Note: don't forget to call the "play()", otherwise the token remains at its original location.

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.

Before we can show a token, we need to set the player colors in the setupNewGame function in reversi.game.php:
<pre>
$default_colors = array( "ffffff", "000000" );
</pre>

Now, to test if everything works fine, just call "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:

[[File:reversi3.jpg]]

== The database ==

We did most of the client-side programming, so let's have a look on the other side now.

To design the database model of our game, 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.

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.

[[File:reversi4.jpg]]

The database model of Reversi is very simple: just one table with the squares of the board. In our dbmodel.sql, we have this:

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

Now, a new database with a "board" table will be created each time we start a Reversi game. This is why after modifying our dbmodel.sql it's a good time to stop & start again our game.

== Setup the initial game position ==

The "setupNewGame" method of our reversi.game.php is called during initial setup: this is the place to initialize our data and to place the initial tokens on the board (initially, there are 4 tokens on the board).

Let's do this:

<pre>
// Init the board
$sql = "INSERT INTO board (board_x,board_y,board_player) VALUES ";
$sql_values = array();
list( $blackplayer_id, $whiteplayer_id ) = array_keys( $players );
for( $x=1; $x<=8; $x++ )
{
for( $y=1; $y<=8; $y++ )
{
$token_value = "NULL";
if( ($x==4 && $y==4) || ($x==5 && $y==5) ) // Initial positions of white player
$token_value = "'$whiteplayer_id'";
else if( ($x==4 && $y==5) || ($x==5 && $y==4) ) // Initial positions of black player
$token_value = "'$blackplayer_id'";

$sql_values[] = "('$x','$y',$token_value)";
}
}
$sql .= implode( $sql_values, ',' );
self::DbQuery( $sql );

// Active first player
self::activeNextPlayer();
</pre>

As you can see, we create one table entry for each square, with a "NULL" value which means "empty square". Of course, for 4 specific squares, we place an initial token.

At the end, we call activeNextPlayer to make the first player active at the beginning of the game.

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

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

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.

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:

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

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

As you can see, our "board" entry created in "getAllDatas" can be used here as "gamedatas.board" in our Javascript. We are using our previously developed "addTokenOnBoard" method.

Reload... and here we are:

[[File:reversi5.jpg]]

It starts to smell Reversi here...

== The game state machine ==

Now, let's stop our game again, because we are going to start the core game logic.

You already read the "Focus on BGA game state machine", so you know that this is the heart of your game logic. For reversi, it's very simple although. Here's a diagram of our game state machine:

[[File:reversi6.jpg]]

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

<pre>
$machinestates = array(

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

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

11 => array(
"name" => "nextPlayer",
"type" => "game",
"action" => "stNextPlayer",
"updateGameProgression" => true,
"transitions" => array( "nextTurn" => 10, "cantPlay" => 11, "endGame" => 99 )
),

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

);
</pre>

Now, let's create in reversi.game.php the methods that are declared in this game states description file:
* argPlayerTurn
* stNextPlayer

... and start a new Reversi game.

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

[[File:reversi7.jpg]]

== The rules ==

Now, what we would like to do is to indicate to the current player where it is allowed to play. The idea is to build a "getPossibleMoves" PHP method that return a list of coordinates where it is allowed to play. This method will be used in particular:
* As we just said, to help the player to see where he can play.
* When the player play, to check if he has the right to play here.

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

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.

If you want to look into details, please look at the "utility method" sections of reversi.game.php.

== Display allowed moves ==

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

To do this, we are using the "argPlayerTurn" method. This method is called each time we enter into "playerTurn" game state, and its result is transfered automatically to the client-side:

<pre>

function argPlayerTurn()
{
return array(
'possibleMoves' => self::getPossibleMoves( self::getActivePlayerId() )
);
}
</pre>

We are of course using the "getPossibleMoves" method we just developed.

Now, let's go to the client side to use the data returned by the method above. We are using the "onEnteringState" Javascript method that is called each time we enter into a new game state:

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

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

So, when we are entering into "playerTurn" game state, we are calling our "updatePossibleMoves" method. This method looks like this:

<pre>
updatePossibleMoves: function( possibleMoves )
{
// Remove current possible moves
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );

for( var x in possibleMoves )
{
for( var y in possibleMoves[ x ] )
{
// x,y is a possible move
dojo.addClass( 'square_'+x+'_'+y, 'possibleMove' );
}
}

this.addTooltipToClass( 'possibleMove', '', _('Place a disc here') );
},
</pre>

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

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

Then we loop through all possible moves our PHP "updatePossibleMoves" function created for us, and add the "possibleMove" class to each corresponding square.

Finally, we use the BGA framework "addTooltipToClass" method to associate a tooltip to all those highlighted squares so that players can understand their meaning.

And here we are:

[[File:reversi8.jpg.jpg]]

== Let's play ==

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

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

<pre>
dojo.query( '.square' ).connect( 'onclick', this, 'onPlayDisc' );
</pre>

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

Here's our "onPlayDisc" method below:

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

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

if( ! dojo.hasClass( 'square_'+x+'_'+y, 'possibleMove' ) )
{
// This is not a possible move => the click does nothing
return ;
}

if( this.checkAction( 'playDisc' ) ) // Check that this action is possible at this moment
{
this.ajaxcall( "/reversi/reversi/playDisc.html", {
x:x,
y:y
}, this, function( result ) {} );
}
},
</pre>

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

Now, we have to manage this "playDisc" action on server side. At first, we introduce a "playDisc" entry point in our "reversi.action.php":

<pre>
public function playDisc()
{
self::setAjaxMode();
$x = self::getArg( "x", AT_posint, true );
$y = self::getArg( "y", AT_posint, true );
$result = $this->game->playDisc( $x, $y );
self::ajaxResponse( );
}
</pre>

As you can see, we get the 2 arguments x and y from the javascript call, and call a corresponding "playDisc" method in our game logic.

Now, let's have a look of this playDisc method:

<pre>
function playDisc( $x, $y )
{
// Check that this player is active and that this action is possible at this moment
self::checkAction( 'playDisc' );
</pre>

... at first, we check that this action is possible according to current game state (see "possible action"). We already did it on client side, but it's important to do it on server side too (otherwise it would be possible to cheat).

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

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

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

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

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

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

self::DbQuery( $sql );

</pre>

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

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

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

</pre>

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

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

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

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

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

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

... finally, we jump to the next game state if everything goes fine ('playDisc' is also the name of a transition in the 'playerTurn' game state description above).
To make the statistics work, we have to initialize them in state.inc.php:

<pre>
// Statistics existing for each player
"player" => array(

"discPlayedOnCorner" => array( "id"=> 10,
"name" => totranslate("Discs played on a corner"),
"type" => "int" ),

"discPlayedOnBorder" => array( "id"=> 11,
"name" => totranslate("Discs played on a border"),
"type" => "int" ),

"discPlayedOnCenter" => array( "id"=> 12,
"name" => totranslate("Discs played on board center part"),
"type" => "int" ),

"turnedOver" => array( "id"=> 13,
"name" => totranslate("Number of discs turned over"),
"type" => "int" )
)
</pre>

A last thing to do on the server side is to activate the next player when we enter the "nextPlayer" game state:

<pre>
function stNextPlayer()
{
// Activate next player
$player_id = self::activeNextPlayer();

self::giveExtraTime( $player_id );
$this->gamestate->nextState( 'nextTurn' );

}
</pre>

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

[[File:reversi9.jpg]]

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

== Make the move appear automatically ==

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

In our "setupNotifications" method, we register 2 methods for the 2 notifications we created at the previous step ('playDisc' and 'turnOverDiscs'):

<pre>
dojo.subscribe( 'playDisc', this, "notif_playDisc" );
this.notifqueue.setSynchronous( 'playDisc', 500 );
dojo.subscribe( 'turnOverDiscs', this, "notif_turnOverDiscs" );
this.notifqueue.setSynchronous( 'turnOverDiscs', 1500 );
</pre>

As you can see, we associate our 2 notifications with 2 methods with the "notif_" prefix. At the same time, we define these notifications as "synchronous", with a duration in millisecond (500 for the first one, and 1500 for the second one). It tells the user interface to wait some time after executing the notification, to let the animation end before starting the next notification. In our specific case, the animation will be the following:
* Make a disc slide from the player panel to its place on the board
* (wait 500ms)
* Make all turned over discs blink (and of course turned them over)
* (wait 1500ms)
* Let the next player play.

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

<pre>
notif_playDisc: function( notif )
{
// Remove current possible moves (makes the board more clear)
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );

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

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

Now, here's the method that handles the turnOverDiscs notification:

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

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

// Make the token blink 2 times
var anim = dojo.fx.chain( [
dojo.fadeOut( { node: 'token_'+token.x+'_'+token.y } ),
dojo.fadeIn( { node: 'token_'+token.x+'_'+token.y } ),
dojo.fadeOut( {
node: 'token_'+token.x+'_'+token.y,
onEnd: function( node ) {

// Remove any color class
dojo.removeClass( node, [ 'tokencolor_000000', 'tokencolor_ffffff' ] );
// ... and add the good one
dojo.addClass( node, 'tokencolor_'+targetColor );

}
} ),
dojo.fadeIn( { node: 'token_'+token.x+'_'+token.y } )

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

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

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

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

Tutorial reversi

2012-12-06T15:32:18Z

Pikiou: /* Let's play */ Need to initialize statistics

== Introduction ==

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

Before you read this tutorial, you must:
* Read the overall presentations of the BGA Framework ([[Studio|see here]]).
* Know the [http://en.wikipedia.org/wiki/Reversi#Rules rules of Reversi].
* Know the languages used on BGA: PHP, SQL, HTML, CSS, Javascript.

== Create your first game ==

With the initial skeleton of code provided initially, you can already start a game from the BGA Studio. For now, we are going to work with 1 player only. Most of the time 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.

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

== Let it look like Reversi ==

It's always a good idea to start with a little bit of graphic work. Why? Because this helps to figure out how the final game will be, and issues that may appear later.

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

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

[[File:Board.jpg]]

Note that we are using a jpg file. Jpg are lighter than png, so faster to load. Later we are going to use PNGs for discs for transparency purpose.

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

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

* edit your reversi.css file to transform it into a visible board:

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

Refresh your page. Here's your board:

[[File:reversi1.jpg]]

== Make the squares appears ==

Now, what we need is to create some invisible HTML elements where squares are. These elements will be used as position references for width and black discs.
Obviously, we need 64 squares. To avoid writing 64 'div' elements on our template, we are going to use the "block" feature.

Let's modify our template like this:

<pre>
<div id="board">

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

</div>
</pre>

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.

Let's do it in our "reversi.view.php" file:

<pre>
$this->page->begin_block( "reversi_reversi", "square" );

$hor_scale = 64.8;
$ver_scale = 64.4;
for( $x=1; $x<=8; $x++ )
{
for( $y=1; $y<=8; $y++ )
{
$this->page->insert_block( "square", array(
'X' => $x,
'Y' => $y,
'LEFT' => round( ($x-1)*$hor_scale+10 ),
'TOP' => round( ($y-1)*$ver_scale+7 )
) );
}
}
</pre>

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.

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

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

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

Explanations:
* With "position: relative" on board, we ensure square elements are positioned relatively to board.
* 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.

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

[[File:reversi2.jpg]]

== The discs ==

Now, our board is ready to receive some disc tokens!

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

<pre>


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

Then, let's introduce a new piece of art with the discs. We need some transparency here so we are using a png file:

[[File:tokens.png]]

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].

Now, let's separate the disc with some CSS stuff:

<pre>
.token {
width: 56px;
height: 56px;
position: absolute;
background-image: url('../../img/reversi/tokens.png');
}
.tokencolor_ffffff { background-position: 0px 0px; }
.tokencolor_000000 { background-position: -56px 0px; }
</pre>

With this CSS code, we apply the classes "token" and "tokencolor_ffffff" to a div element and we've got a white token. Yeah.

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

Now, let's make a first token appear on our board. Disc tokens are not visible at the beginning of the game: they appear dynamically during the game. For this reason, we are going to make them appear from our Javascript code, with a BGA Framework technique called "JS template".

In our template file (reversi_reversi.tpl), let's create the piece of HTML needed to display our token:

<pre>
<script type="text/javascript">

// Templates

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

</script>
</pre>

Note: we already created the "templates" section for you in the game skeleton.

As you can see, we defined a JS template named "jstpl_token" with a piece of HTML and two variables: the color of the token and its x/y coordinates. Note that the syntax of the argument is different for template block variables (brackets) and JS template variables (dollar and brackets).

Now, let's create a method in our Javascript code that will make a token appear on the board, using this template:

<pre>
addTokenOnBoard: function( x, y, player )
{
dojo.place( this.format_block( 'jstpl_token', {
x_y: x+'_'+y,
color: this.gamedatas.players[ player ].color
} ) , 'tokens' );

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

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.

Then, with BGA "this.placeOnObject" method, we place this element over the panel of some player. Immediately after, using BGA "this.slidetoObject" method, we make the disc slide to the "square" element, its final destination.

Note: don't forget to call the "play()", otherwise the token remains at its original location.

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.

Before we can show a token, we need to set the player colors in the setupNewGame function in reversi.game.php:
<pre>
$default_colors = array( "ffffff", "000000" );
</pre>

Now, to test if everything works fine, just call "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:

[[File:reversi3.jpg]]

== The database ==

We did most of the client-side programming, so let's have a look on the other side now.

To design the database model of our game, 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.

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.

[[File:reversi4.jpg]]

The database model of Reversi is very simple: just one table with the squares of the board. In our dbmodel.sql, we have this:

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

Now, a new database with a "board" table will be created each time we start a Reversi game. This is why after modifying our dbmodel.sql it's a good time to stop & start again our game.

== Setup the initial game position ==

The "setupNewGame" method of our reversi.game.php is called during initial setup: this is the place to initialize our data and to place the initial tokens on the board (initially, there are 4 tokens on the board).

Let's do this:

<pre>
// Init the board
$sql = "INSERT INTO board (board_x,board_y,board_player) VALUES ";
$sql_values = array();
list( $blackplayer_id, $whiteplayer_id ) = array_keys( $players );
for( $x=1; $x<=8; $x++ )
{
for( $y=1; $y<=8; $y++ )
{
$token_value = "NULL";
if( ($x==4 && $y==4) || ($x==5 && $y==5) ) // Initial positions of white player
$token_value = "'$whiteplayer_id'";
else if( ($x==4 && $y==5) || ($x==5 && $y==4) ) // Initial positions of black player
$token_value = "'$blackplayer_id'";

$sql_values[] = "('$x','$y',$token_value)";
}
}
$sql .= implode( $sql_values, ',' );
self::DbQuery( $sql );

// Active first player
self::activeNextPlayer();
</pre>

As you can see, we create one table entry for each square, with a "NULL" value which means "empty square". Of course, for 4 specific squares, we place an initial token.

At the end, we call activeNextPlayer to make the first player active at the beginning of the game.

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

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

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.

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:

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

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

As you can see, our "board" entry created in "getAllDatas" can be used here as "gamedatas.board" in our Javascript. We are using our previously developed "addTokenOnBoard" method.

Reload... and here we are:

[[File:reversi5.jpg]]

It starts to smell Reversi here...

== The game state machine ==

Now, let's stop our game again, because we are going to start the core game logic.

You already read the "Focus on BGA game state machine", so you know that this is the heart of your game logic. For reversi, it's very simple although. Here's a diagram of our game state machine:

[[File:reversi6.jpg]]

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

<pre>
$machinestates = array(

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

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

11 => array(
"name" => "nextPlayer",
"type" => "game",
"action" => "stNextPlayer",
"updateGameProgression" => true,
"transitions" => array( "nextTurn" => 10, "cantPlay" => 11, "endGame" => 99 )
),

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

);
</pre>

Now, let's create in reversi.game.php the methods that are declared in this game states description file:
* argPlayerTurn
* stNextPlayer

... and start a new Reversi game.

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

[[File:reversi7.jpg]]

== The rules ==

Now, what we would like to do is to indicate to the current player where it is allowed to play. The idea is to build a "getPossibleMoves" PHP method that return a list of coordinates where it is allowed to play. This method will be used in particular:
* As we just said, to help the player to see where he can play.
* When the player play, to check if he has the right to play here.

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

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.

If you want to look into details, please look at the "utility method" sections of reversi.game.php.

== Display allowed moves ==

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

To do this, we are using the "argPlayerTurn" method. This method is called each time we enter into "playerTurn" game state, and its result is transfered automatically to the client-side:

<pre>

function argPlayerTurn()
{
return array(
'possibleMoves' => self::getPossibleMoves( self::getActivePlayerId() )
);
}
</pre>

We are of course using the "getPossibleMoves" method we just developed.

Now, let's go to the client side to use the data returned by the method above. We are using the "onEnteringState" Javascript method that is called each time we enter into a new game state:

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

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

So, when we are entering into "playerTurn" game state, we are calling our "updatePossibleMoves" method. This method looks like this:

<pre>
updatePossibleMoves: function( possibleMoves )
{
// Remove current possible moves
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );

for( var x in possibleMoves )
{
for( var y in possibleMoves[ x ] )
{
// x,y is a possible move
dojo.addClass( 'square_'+x+'_'+y, 'possibleMove' );
}
}

this.addTooltipToClass( 'possibleMove', '', _('Place a disc here') );
},
</pre>

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

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

Then we loop through all possible moves our PHP "updatePossibleMoves" function created for us, and add the "possibleMove" class to each corresponding square.

Finally, we use the BGA framework "addTooltipToClass" method to associate a tooltip to all those highlighted squares so that players can understand their meaning.

And here we are:

[[File:reversi8.jpg.jpg]]

== Let's play ==

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

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

<pre>
dojo.query( '.square' ).connect( 'onclick', this, 'onPlayDisc' );
</pre>

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

Here's our "onPlayDisc" method below:

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

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

if( ! dojo.hasClass( 'square_'+x+'_'+y, 'possibleMove' ) )
{
// This is not a possible move => the click does nothing
return ;
}

if( this.checkAction( 'playDisc' ) ) // Check that this action is possible at this moment
{
this.ajaxcall( "/reversi/reversi/playDisc.html", {
x:x,
y:y
}, this, function( result ) {} );
}
},
</pre>

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

Now, we have to manage this "playDisc" action on server side. At first, we introduce a "playDisc" entry point in our "reversi.action.php":

<pre>
public function playDisc()
{
self::setAjaxMode();
$x = self::getArg( "x", AT_posint, true );
$y = self::getArg( "y", AT_posint, true );
$result = $this->game->playDisc( $x, $y );
self::ajaxResponse( );
}
</pre>

As you can see, we get the 2 arguments x and y from the javascript call, and call a corresponding "playDisc" method in our game logic.

Now, let's have a look of this playDisc method:

<pre>
function playDisc( $x, $y )
{
// Check that this player is active and that this action is possible at this moment
self::checkAction( 'playDisc' );
</pre>

... at first, we check that this action is possible according to current game state (see "possible action"). We already did it on client side, but it's important to do it on server side too (otherwise it would be possible to cheat).

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

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

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

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

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

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

self::DbQuery( $sql );

</pre>

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

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

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

</pre>

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

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

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

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

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

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

... finally, we jump to the next game state if everything goes fine ('playDisc' is also the name of a transition in the 'playerTurn' game state description above).
To make the statistics work, we have to initialize them in state.inc.php:

<pre>
// Statistics existing for each player
"player" => array(

"discPlayedOnCorner" => array( "id"=> 10,
"name" => totranslate("Discs played on a corner"),
"type" => "int" ),

"discPlayedOnBorder" => array( "id"=> 11,
"name" => totranslate("Discs played on a border"),
"type" => "int" ),

"discPlayedOnCenter" => array( "id"=> 12,
"name" => totranslate("Discs played on board center part"),
"type" => "int" ),

"turnedOver" => array( "id"=> 13,
"name" => totranslate("Number of discs turned over"),
"type" => "int" )
)
</pre>

A last thing to do on the server side is to activate the next player when we enter the "nextPlayer" game state:

<pre>
function stNextPlayer()
{
// Activate next player
$player_id = self::activeNextPlayer();

self::giveExtraTime( $player_id );
$this->gamestate->nextState( 'nextTurn' );

}
</pre>

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

[[File:reversi9.jpg]]

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

== Make the move appears automatically ==

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

In our "setupNotifications" method, we register 2 methods for the 2 notifications we created at the previous step ('playDisc' and 'turnOverDiscs'):

<pre>
dojo.subscribe( 'playDisc', this, "notif_playDisc" );
this.notifqueue.setSynchronous( 'playDisc', 500 );
dojo.subscribe( 'turnOverDiscs', this, "notif_turnOverDiscs" );
this.notifqueue.setSynchronous( 'turnOverDiscs', 1500 );
</pre>

As you can see, we associate our 2 notifications with 2 methods with the "notif_" prefix. At the same time, we define these notifications as "synchronous", with a duration in millisecond (500 for the first one, and 1500 for the second one). It tells the user interface to wait some time after executing the notification, to let the animation end before starting the next notification. In our specific case, the animation will be the following:
* Make a disc slide from the player panel to its place on the board
* (wait 500ms)
* Make all turned over discs blink (and of course turned them over)
* (wait 1500ms)
* Let the next player play.

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

<pre>
notif_playDisc: function( notif )
{
// Remove current possible moves (makes the board more clear)
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );

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

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

Now, here's the method that handle the turnOverDiscs notification:

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

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

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

// Remove any color class
dojo.removeClass( node, [ 'disccolor_000000', 'disccolor_ffffff' ] );
// ... and add the good one
dojo.addClass( node, 'disccolor_'+targetColor );

}
} ),
dojo.fadeIn( { node: 'disc_'+disc.x+''+disc.y } )

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

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

The list of the discs 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 it. The complete documentation on dojo animations [http://dojotoolkit.org/documentation/tutorials/1.6/animation/ can be found here].

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

Tutorial reversi

2012-12-06T15:30:58Z

Pikiou: /* Let's play */ Typos

== Introduction ==

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

Before you read this tutorial, you must:
* Read the overall presentations of the BGA Framework ([[Studio|see here]]).
* Know the [http://en.wikipedia.org/wiki/Reversi#Rules rules of Reversi].
* Know the languages used on BGA: PHP, SQL, HTML, CSS, Javascript.

== Create your first game ==

With the initial skeleton of code provided initially, you can already start a game from the BGA Studio. For now, we are going to work with 1 player only. Most of the time 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.

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

== Let it look like Reversi ==

It's always a good idea to start with a little bit of graphic work. Why? Because this helps to figure out how the final game will be, and issues that may appear later.

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

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

[[File:Board.jpg]]

Note that we are using a jpg file. Jpg are lighter than png, so faster to load. Later we are going to use PNGs for discs for transparency purpose.

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

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

* edit your reversi.css file to transform it into a visible board:

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

Refresh your page. Here's your board:

[[File:reversi1.jpg]]

== Make the squares appears ==

Now, what we need is to create some invisible HTML elements where squares are. These elements will be used as position references for width and black discs.
Obviously, we need 64 squares. To avoid writing 64 'div' elements on our template, we are going to use the "block" feature.

Let's modify our template like this:

<pre>
<div id="board">

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

</div>
</pre>

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.

Let's do it in our "reversi.view.php" file:

<pre>
$this->page->begin_block( "reversi_reversi", "square" );

$hor_scale = 64.8;
$ver_scale = 64.4;
for( $x=1; $x<=8; $x++ )
{
for( $y=1; $y<=8; $y++ )
{
$this->page->insert_block( "square", array(
'X' => $x,
'Y' => $y,
'LEFT' => round( ($x-1)*$hor_scale+10 ),
'TOP' => round( ($y-1)*$ver_scale+7 )
) );
}
}
</pre>

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.

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

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

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

Explanations:
* With "position: relative" on board, we ensure square elements are positioned relatively to board.
* 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.

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

[[File:reversi2.jpg]]

== The discs ==

Now, our board is ready to receive some disc tokens!

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

<pre>


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

Then, let's introduce a new piece of art with the discs. We need some transparency here so we are using a png file:

[[File:tokens.png]]

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].

Now, let's separate the disc with some CSS stuff:

<pre>
.token {
width: 56px;
height: 56px;
position: absolute;
background-image: url('../../img/reversi/tokens.png');
}
.tokencolor_ffffff { background-position: 0px 0px; }
.tokencolor_000000 { background-position: -56px 0px; }
</pre>

With this CSS code, we apply the classes "token" and "tokencolor_ffffff" to a div element and we've got a white token. Yeah.

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

Now, let's make a first token appear on our board. Disc tokens are not visible at the beginning of the game: they appear dynamically during the game. For this reason, we are going to make them appear from our Javascript code, with a BGA Framework technique called "JS template".

In our template file (reversi_reversi.tpl), let's create the piece of HTML needed to display our token:

<pre>
<script type="text/javascript">

// Templates

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

</script>
</pre>

Note: we already created the "templates" section for you in the game skeleton.

As you can see, we defined a JS template named "jstpl_token" with a piece of HTML and two variables: the color of the token and its x/y coordinates. Note that the syntax of the argument is different for template block variables (brackets) and JS template variables (dollar and brackets).

Now, let's create a method in our Javascript code that will make a token appear on the board, using this template:

<pre>
addTokenOnBoard: function( x, y, player )
{
dojo.place( this.format_block( 'jstpl_token', {
x_y: x+'_'+y,
color: this.gamedatas.players[ player ].color
} ) , 'tokens' );

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

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.

Then, with BGA "this.placeOnObject" method, we place this element over the panel of some player. Immediately after, using BGA "this.slidetoObject" method, we make the disc slide to the "square" element, its final destination.

Note: don't forget to call the "play()", otherwise the token remains at its original location.

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.

Before we can show a token, we need to set the player colors in the setupNewGame function in reversi.game.php:
<pre>
$default_colors = array( "ffffff", "000000" );
</pre>

Now, to test if everything works fine, just call "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:

[[File:reversi3.jpg]]

== The database ==

We did most of the client-side programming, so let's have a look on the other side now.

To design the database model of our game, 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.

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.

[[File:reversi4.jpg]]

The database model of Reversi is very simple: just one table with the squares of the board. In our dbmodel.sql, we have this:

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

Now, a new database with a "board" table will be created each time we start a Reversi game. This is why after modifying our dbmodel.sql it's a good time to stop & start again our game.

== Setup the initial game position ==

The "setupNewGame" method of our reversi.game.php is called during initial setup: this is the place to initialize our data and to place the initial tokens on the board (initially, there are 4 tokens on the board).

Let's do this:

<pre>
// Init the board
$sql = "INSERT INTO board (board_x,board_y,board_player) VALUES ";
$sql_values = array();
list( $blackplayer_id, $whiteplayer_id ) = array_keys( $players );
for( $x=1; $x<=8; $x++ )
{
for( $y=1; $y<=8; $y++ )
{
$token_value = "NULL";
if( ($x==4 && $y==4) || ($x==5 && $y==5) ) // Initial positions of white player
$token_value = "'$whiteplayer_id'";
else if( ($x==4 && $y==5) || ($x==5 && $y==4) ) // Initial positions of black player
$token_value = "'$blackplayer_id'";

$sql_values[] = "('$x','$y',$token_value)";
}
}
$sql .= implode( $sql_values, ',' );
self::DbQuery( $sql );

// Active first player
self::activeNextPlayer();
</pre>

As you can see, we create one table entry for each square, with a "NULL" value which means "empty square". Of course, for 4 specific squares, we place an initial token.

At the end, we call activeNextPlayer to make the first player active at the beginning of the game.

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

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

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.

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:

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

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

As you can see, our "board" entry created in "getAllDatas" can be used here as "gamedatas.board" in our Javascript. We are using our previously developed "addTokenOnBoard" method.

Reload... and here we are:

[[File:reversi5.jpg]]

It starts to smell Reversi here...

== The game state machine ==

Now, let's stop our game again, because we are going to start the core game logic.

You already read the "Focus on BGA game state machine", so you know that this is the heart of your game logic. For reversi, it's very simple although. Here's a diagram of our game state machine:

[[File:reversi6.jpg]]

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

<pre>
$machinestates = array(

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

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

11 => array(
"name" => "nextPlayer",
"type" => "game",
"action" => "stNextPlayer",
"updateGameProgression" => true,
"transitions" => array( "nextTurn" => 10, "cantPlay" => 11, "endGame" => 99 )
),

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

);
</pre>

Now, let's create in reversi.game.php the methods that are declared in this game states description file:
* argPlayerTurn
* stNextPlayer

... and start a new Reversi game.

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

[[File:reversi7.jpg]]

== The rules ==

Now, what we would like to do is to indicate to the current player where it is allowed to play. The idea is to build a "getPossibleMoves" PHP method that return a list of coordinates where it is allowed to play. This method will be used in particular:
* As we just said, to help the player to see where he can play.
* When the player play, to check if he has the right to play here.

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

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.

If you want to look into details, please look at the "utility method" sections of reversi.game.php.

== Display allowed moves ==

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

To do this, we are using the "argPlayerTurn" method. This method is called each time we enter into "playerTurn" game state, and its result is transfered automatically to the client-side:

<pre>

function argPlayerTurn()
{
return array(
'possibleMoves' => self::getPossibleMoves( self::getActivePlayerId() )
);
}
</pre>

We are of course using the "getPossibleMoves" method we just developed.

Now, let's go to the client side to use the data returned by the method above. We are using the "onEnteringState" Javascript method that is called each time we enter into a new game state:

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

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

So, when we are entering into "playerTurn" game state, we are calling our "updatePossibleMoves" method. This method looks like this:

<pre>
updatePossibleMoves: function( possibleMoves )
{
// Remove current possible moves
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );

for( var x in possibleMoves )
{
for( var y in possibleMoves[ x ] )
{
// x,y is a possible move
dojo.addClass( 'square_'+x+'_'+y, 'possibleMove' );
}
}

this.addTooltipToClass( 'possibleMove', '', _('Place a disc here') );
},
</pre>

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

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

Then we loop through all possible moves our PHP "updatePossibleMoves" function created for us, and add the "possibleMove" class to each corresponding square.

Finally, we use the BGA framework "addTooltipToClass" method to associate a tooltip to all those highlighted squares so that players can understand their meaning.

And here we are:

[[File:reversi8.jpg.jpg]]

== Let's play ==

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

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

<pre>
dojo.query( '.square' ).connect( 'onclick', this, 'onPlayDisc' );
</pre>

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

Here's our "onPlayDisc" method below:

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

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

if( ! dojo.hasClass( 'square_'+x+'_'+y, 'possibleMove' ) )
{
// This is not a possible move => the click does nothing
return ;
}

if( this.checkAction( 'playDisc' ) ) // Check that this action is possible at this moment
{
this.ajaxcall( "/reversi/reversi/playDisc.html", {
x:x,
y:y
}, this, function( result ) {} );
}
},
</pre>

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

Now, we have to manage this "playDisc" action on server side. At first, we introduce a "playDisc" entry point in our "reversi.action.php":

<pre>
public function playDisc()
{
self::setAjaxMode();
$x = self::getArg( "x", AT_posint, true );
$y = self::getArg( "y", AT_posint, true );
$result = $this->game->playDisc( $x, $y );
self::ajaxResponse( );
}
</pre>

As you can see, we get the 2 arguments x and y from the javascript call, and call a corresponding "playDisc" method in our game logic.

Now, let's have a look of this playDisc method:

<pre>
function playDisc( $x, $y )
{
// Check that this player is active and that this action is possible at this moment
self::checkAction( 'playDisc' );
</pre>

... at first, we check that this action is possible according to current game state (see "possible action"). We already did it on client side, but it's important to do it on server side too (otherwise it would be possible to cheat).

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

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

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

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

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

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

self::DbQuery( $sql );

</pre>

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

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

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

</pre>

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

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

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

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

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

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

... finally, we jump to the next game state if everything goes fine ('playDisc' is also the name of a transition in the 'playerTurn' game state description above).
A last thing to do on the server side is to activate the next player when we enter the "nextPlayer" game state:

<pre>
function stNextPlayer()
{
// Activate next player
$player_id = self::activeNextPlayer();

self::giveExtraTime( $player_id );
$this->gamestate->nextState( 'nextTurn' );

}
</pre>

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

[[File:reversi9.jpg]]

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

== Make the move appears automatically ==

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

In our "setupNotifications" method, we register 2 methods for the 2 notifications we created at the previous step ('playDisc' and 'turnOverDiscs'):

<pre>
dojo.subscribe( 'playDisc', this, "notif_playDisc" );
this.notifqueue.setSynchronous( 'playDisc', 500 );
dojo.subscribe( 'turnOverDiscs', this, "notif_turnOverDiscs" );
this.notifqueue.setSynchronous( 'turnOverDiscs', 1500 );
</pre>

As you can see, we associate our 2 notifications with 2 methods with the "notif_" prefix. At the same time, we define these notifications as "synchronous", with a duration in millisecond (500 for the first one, and 1500 for the second one). It tells the user interface to wait some time after executing the notification, to let the animation end before starting the next notification. In our specific case, the animation will be the following:
* Make a disc slide from the player panel to its place on the board
* (wait 500ms)
* Make all turned over discs blink (and of course turned them over)
* (wait 1500ms)
* Let the next player play.

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

<pre>
notif_playDisc: function( notif )
{
// Remove current possible moves (makes the board more clear)
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );

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

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

Now, here's the method that handle the turnOverDiscs notification:

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

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

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

// Remove any color class
dojo.removeClass( node, [ 'disccolor_000000', 'disccolor_ffffff' ] );
// ... and add the good one
dojo.addClass( node, 'disccolor_'+targetColor );

}
} ),
dojo.fadeIn( { node: 'disc_'+disc.x+''+disc.y } )

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

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

The list of the discs 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 it. The complete documentation on dojo animations [http://dojotoolkit.org/documentation/tutorials/1.6/animation/ can be found here].

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

Tutorial reversi

2012-12-06T12:28:33Z

Pikiou: /* Make the squares appears */ Squares didn't fill their space

== Introduction ==

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

Before you read this tutorial, you must:
* Read the overall presentations of the BGA Framework ([[Studio|see here]]).
* Know the [http://en.wikipedia.org/wiki/Reversi#Rules rules of Reversi].
* Know the languages used on BGA: PHP, SQL, HTML, CSS, Javascript.

== Create your first game ==

With the initial skeleton of code provided initially, you can already start a game from the BGA Studio. For now, we are going to work with 1 player only. Most of the time 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.

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

== Let it look like Reversi ==

It's always a good idea to start with a little bit of graphic work. Why? Because this helps to figure out how the final game will be, and issues that may appear later.

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

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

[[File:Board.jpg]]

Note that we are using a jpg file. Jpg are lighter than png, so faster to load. Later we are going to use PNGs for discs for transparency purpose.

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

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

* edit your reversi.css file to transform it into a visible board:

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

Refresh your page. Here's your board:

[[File:reversi1.jpg]]

== Make the squares appears ==

Now, what we need is to create some invisible HTML elements where squares are. These elements will be used as position references for width and black discs.
Obviously, we need 64 squares. To avoid writing 64 'div' elements on our template, we are going to use the "block" feature.

Let's modify our template like this:

<pre>
<div id="board">

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

</div>
</pre>

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.

Let's do it in our "reversi.view.php" file:

<pre>
$this->page->begin_block( "reversi_reversi", "square" );

$hor_scale = 64.8;
$ver_scale = 64.4;
for( $x=1; $x<=8; $x++ )
{
for( $y=1; $y<=8; $y++ )
{
$this->page->insert_block( "square", array(
'X' => $x,
'Y' => $y,
'LEFT' => round( ($x-1)*$hor_scale+10 ),
'TOP' => round( ($y-1)*$ver_scale+7 )
) );
}
}
</pre>

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.

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

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

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

Explanations:
* With "position: relative" on board, we ensure square elements are positioned relatively to board.
* 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.

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

[[File:reversi2.jpg]]

== The discs ==

Now, our board is ready to receive some disc tokens!

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

<pre>


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

Then, let's introduce a new piece of art with the discs. We need some transparency here so we are using a png file:

[[File:tokens.png]]

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].

Now, let's separate the disc with some CSS stuff:

<pre>
.token {
width: 56px;
height: 56px;
position: absolute;
background-image: url('../../img/reversi/tokens.png');
}
.tokencolor_ffffff { background-position: 0px 0px; }
.tokencolor_000000 { background-position: -56px 0px; }
</pre>

With this CSS code, we apply the classes "token" and "tokencolor_ffffff" to a div element and we've got a white token. Yeah.

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

Now, let's make a first token appear on our board. Disc tokens are not visible at the beginning of the game: they appear dynamically during the game. For this reason, we are going to make them appear from our Javascript code, with a BGA Framework technique called "JS template".

In our template file (reversi_reversi.tpl), let's create the piece of HTML needed to display our token:

<pre>
<script type="text/javascript">

// Templates

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

</script>
</pre>

Note: we already created the "templates" section for you in the game skeleton.

As you can see, we defined a JS template named "jstpl_token" with a piece of HTML and two variables: the color of the token and its x/y coordinates. Note that the syntax of the argument is different for template block variables (brackets) and JS template variables (dollar and brackets).

Now, let's create a method in our Javascript code that will make a token appear on the board, using this template:

<pre>
addTokenOnBoard: function( x, y, player )
{
dojo.place( this.format_block( 'jstpl_token', {
x_y: x+'_'+y,
color: this.gamedatas.players[ player ].color
} ) , 'tokens' );

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

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.

Then, with BGA "this.placeOnObject" method, we place this element over the panel of some player. Immediately after, using BGA "this.slidetoObject" method, we make the disc slide to the "square" element, its final destination.

Note: don't forget to call the "play()", otherwise the token remains at its original location.

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.

Before we can show a token, we need to set the player colors in the setupNewGame function in reversi.game.php:
<pre>
$default_colors = array( "ffffff", "000000" );
</pre>

Now, to test if everything works fine, just call "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:

[[File:reversi3.jpg]]

== The database ==

We did most of the client-side programming, so let's have a look on the other side now.

To design the database model of our game, 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.

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.

[[File:reversi4.jpg]]

The database model of Reversi is very simple: just one table with the squares of the board. In our dbmodel.sql, we have this:

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

Now, a new database with a "board" table will be created each time we start a Reversi game. This is why after modifying our dbmodel.sql it's a good time to stop & start again our game.

== Setup the initial game position ==

The "setupNewGame" method of our reversi.game.php is called during initial setup: this is the place to initialize our data and to place the initial tokens on the board (initially, there are 4 tokens on the board).

Let's do this:

<pre>
// Init the board
$sql = "INSERT INTO board (board_x,board_y,board_player) VALUES ";
$sql_values = array();
list( $blackplayer_id, $whiteplayer_id ) = array_keys( $players );
for( $x=1; $x<=8; $x++ )
{
for( $y=1; $y<=8; $y++ )
{
$token_value = "NULL";
if( ($x==4 && $y==4) || ($x==5 && $y==5) ) // Initial positions of white player
$token_value = "'$whiteplayer_id'";
else if( ($x==4 && $y==5) || ($x==5 && $y==4) ) // Initial positions of black player
$token_value = "'$blackplayer_id'";

$sql_values[] = "('$x','$y',$token_value)";
}
}
$sql .= implode( $sql_values, ',' );
self::DbQuery( $sql );

// Active first player
self::activeNextPlayer();
</pre>

As you can see, we create one table entry for each square, with a "NULL" value which means "empty square". Of course, for 4 specific squares, we place an initial token.

At the end, we call activeNextPlayer to make the first player active at the beginning of the game.

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

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

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.

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:

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

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

As you can see, our "board" entry created in "getAllDatas" can be used here as "gamedatas.board" in our Javascript. We are using our previously developed "addTokenOnBoard" method.

Reload... and here we are:

[[File:reversi5.jpg]]

It starts to smell Reversi here...

== The game state machine ==

Now, let's stop our game again, because we are going to start the core game logic.

You already read the "Focus on BGA game state machine", so you know that this is the heart of your game logic. For reversi, it's very simple although. Here's a diagram of our game state machine:

[[File:reversi6.jpg]]

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

<pre>
$machinestates = array(

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

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

11 => array(
"name" => "nextPlayer",
"type" => "game",
"action" => "stNextPlayer",
"updateGameProgression" => true,
"transitions" => array( "nextTurn" => 10, "cantPlay" => 11, "endGame" => 99 )
),

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

);
</pre>

Now, let's create in reversi.game.php the methods that are declared in this game states description file:
* argPlayerTurn
* stNextPlayer

... and start a new Reversi game.

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

[[File:reversi7.jpg]]

== The rules ==

Now, what we would like to do is to indicate to the current player where it is allowed to play. The idea is to build a "getPossibleMoves" PHP method that return a list of coordinates where it is allowed to play. This method will be used in particular:
* As we just said, to help the player to see where he can play.
* When the player play, to check if he has the right to play here.

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

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.

If you want to look into details, please look at the "utility method" sections of reversi.game.php.

== Display allowed moves ==

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

To do this, we are using the "argPlayerTurn" method. This method is called each time we enter into "playerTurn" game state, and its result is transfered automatically to the client-side:

<pre>

function argPlayerTurn()
{
return array(
'possibleMoves' => self::getPossibleMoves( self::getActivePlayerId() )
);
}
</pre>

We are of course using the "getPossibleMoves" method we just developed.

Now, let's go to the client side to use the data returned by the method above. We are using the "onEnteringState" Javascript method that is called each time we enter into a new game state:

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

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

So, when we are entering into "playerTurn" game state, we are calling our "updatePossibleMoves" method. This method looks like this:

<pre>
updatePossibleMoves: function( possibleMoves )
{
// Remove current possible moves
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );

for( var x in possibleMoves )
{
for( var y in possibleMoves[ x ] )
{
// x,y is a possible move
dojo.addClass( 'square_'+x+'_'+y, 'possibleMove' );
}
}

this.addTooltipToClass( 'possibleMove', '', _('Place a disc here') );
},
</pre>

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

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

Then we loop through all possible moves our PHP "updatePossibleMoves" function created for us, and add the "possibleMove" class to each corresponding square.

Finally, we use the BGA framework "addTooltipToClass" method to associate a tooltip to all those highlighted squares so that players can understand their meaning.

And here we are:

[[File:reversi8.jpg.jpg]]

== Let's play ==

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

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

<pre>
dojo.query( '.square' ).connect( 'onclick', this, 'onPlayDisc' );
</pre>

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

Here's our "onPlayDisc" method below:

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

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

if( ! dojo.hasClass( 'square_'+x+'_'+y, 'possibleMove' ) )
{
// This is not a possible move => the click does nothing
return ;
}

if( this.checkAction( 'playDisc' ) ) // Check that this action is possible at this moment
{
this.ajaxcall( "/reversi/reversi/playDisc.html", {
x:x,
y:y
}, this, function( result ) {} );
}
},
</pre>

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

Now, we have to manage this "playDisc" action on server side. At first, we introduce a "playDisc" entry point in our "reversi.action.php":

<pre>
public function playDisc()
{
self::setAjaxMode();
$x = self::getArg( "x", AT_posint, true );
$y = self::getArg( "y", AT_posint, true );
$result = $this->game->playDisc( $x, $y );
self::ajaxResponse( );
}
</pre>

As you can see, we get the 2 arguments x and y from the javascript call, and call a corresponding "playDisc" method in our game logic.

Now, let's have a look of this playDisc method:

<pre>
function playDisc( $x, $y )
{
// Check that this player is active and that this action is possible at this moment
self::checkAction( 'playDisc' );
</pre>

... at first, we check that this action is possible according to current game state (see "possible action"). We already did it on client side, but it's important to do it on server side too (otherwise it would be possible to cheat).

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

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

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

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

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

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

self::DbQuery( $sql );

</pre>

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

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

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

</pre>

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

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

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

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

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

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

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

A last thing to do on the server side is to active the next player when we enter in the "nextPlayer" game state:

<pre>
function stNextPlayer()
{
// Active next player
$player_id = self::activeNextPlayer();

self::giveExtraTime( $player_id );
$this->gamestate->nextState( 'nextTurn' );

}
</pre>

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

[[File:reversi9.jpg]]

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

== Make the move appears automatically ==

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

In our "setupNotifications" method, we register 2 methods for the 2 notifications we created at the previous step ('playDisc' and 'turnOverDiscs'):

<pre>
dojo.subscribe( 'playDisc', this, "notif_playDisc" );
this.notifqueue.setSynchronous( 'playDisc', 500 );
dojo.subscribe( 'turnOverDiscs', this, "notif_turnOverDiscs" );
this.notifqueue.setSynchronous( 'turnOverDiscs', 1500 );
</pre>

As you can see, we associate our 2 notifications with 2 methods with the "notif_" prefix. At the same time, we define these notifications as "synchronous", with a duration in millisecond (500 for the first one, and 1500 for the second one). It tells the user interface to wait some time after executing the notification, to let the animation end before starting the next notification. In our specific case, the animation will be the following:
* Make a disc slide from the player panel to its place on the board
* (wait 500ms)
* Make all turned over discs blink (and of course turned them over)
* (wait 1500ms)
* Let the next player play.

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

<pre>
notif_playDisc: function( notif )
{
// Remove current possible moves (makes the board more clear)
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );

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

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

Now, here's the method that handle the turnOverDiscs notification:

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

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

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

// Remove any color class
dojo.removeClass( node, [ 'disccolor_000000', 'disccolor_ffffff' ] );
// ... and add the good one
dojo.addClass( node, 'disccolor_'+targetColor );

}
} ),
dojo.fadeIn( { node: 'disc_'+disc.x+''+disc.y } )

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

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

The list of the discs 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 it. The complete documentation on dojo animations [http://dojotoolkit.org/documentation/tutorials/1.6/animation/ can be found here].

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

Tutorial reversi

2012-12-06T12:11:08Z

Pikiou: /* Display allowed moves */ Typos

== Introduction ==

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

Before you read this tutorial, you must:
* Read the overall presentations of the BGA Framework ([[Studio|see here]]).
* Know the [http://en.wikipedia.org/wiki/Reversi#Rules rules of Reversi].
* Know the languages used on BGA: PHP, SQL, HTML, CSS, Javascript.

== Create your first game ==

With the initial skeleton of code provided initially, you can already start a game from the BGA Studio. For now, we are going to work with 1 player only. Most of the time 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.

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

== Let it look like Reversi ==

It's always a good idea to start with a little bit of graphic work. Why? Because this helps to figure out how the final game will be, and issues that may appear later.

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

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

[[File:Board.jpg]]

Note that we are using a jpg file. Jpg are lighter than png, so faster to load. Later we are going to use PNGs for discs for transparency purpose.

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

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

* edit your reversi.css file to transform it into a visible board:

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

Refresh your page. Here's your board:

[[File:reversi1.jpg]]

== Make the squares appears ==

Now, what we need is to create some invisible HTML elements where squares are. These elements will be used as position references for width and black discs.
Obviously, we need 64 squares. To avoid writing 64 'div' elements on our template, we are going to use the "block" feature.

Let's modify our template like this:

<pre>
<div id="board">

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

</div>
</pre>

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.

Let's do it in our "reversi.view.php" file:

<pre>
$this->page->begin_block( "reversi_reversi", "square" );

$hor_scale = 64.8;
$ver_scale = 64.4;
for( $x=1; $x<=8; $x++ )
{
for( $y=1; $y<=8; $y++ )
{
$this->page->insert_block( "square", array(
'X' => $x,
'Y' => $y,
'LEFT' => round( ($x-1)*$hor_scale+10 ),
'TOP' => round( ($y-1)*$ver_scale+7 )
) );
}
}
</pre>

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.

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

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

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

Explanations:
* With "position: relative" on board, we ensure square elements are positioned relatively to board.
* For the test, we use a red background color for the square. This is a useful tip to figure out if everything is fine with invisible elements.

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

[[File:reversi2.jpg]]

== The discs ==

Now, our board is ready to receive some disc tokens!

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

<pre>


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

Then, let's introduce a new piece of art with the discs. We need some transparency here so we are using a png file:

[[File:tokens.png]]

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].

Now, let's separate the disc with some CSS stuff:

<pre>
.token {
width: 56px;
height: 56px;
position: absolute;
background-image: url('../../img/reversi/tokens.png');
}
.tokencolor_ffffff { background-position: 0px 0px; }
.tokencolor_000000 { background-position: -56px 0px; }
</pre>

With this CSS code, we apply the classes "token" and "tokencolor_ffffff" to a div element and we've got a white token. Yeah.

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

Now, let's make a first token appear on our board. Disc tokens are not visible at the beginning of the game: they appear dynamically during the game. For this reason, we are going to make them appear from our Javascript code, with a BGA Framework technique called "JS template".

In our template file (reversi_reversi.tpl), let's create the piece of HTML needed to display our token:

<pre>
<script type="text/javascript">

// Templates

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

</script>
</pre>

Note: we already created the "templates" section for you in the game skeleton.

As you can see, we defined a JS template named "jstpl_token" with a piece of HTML and two variables: the color of the token and its x/y coordinates. Note that the syntax of the argument is different for template block variables (brackets) and JS template variables (dollar and brackets).

Now, let's create a method in our Javascript code that will make a token appear on the board, using this template:

<pre>
addTokenOnBoard: function( x, y, player )
{
dojo.place( this.format_block( 'jstpl_token', {
x_y: x+'_'+y,
color: this.gamedatas.players[ player ].color
} ) , 'tokens' );

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

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.

Then, with BGA "this.placeOnObject" method, we place this element over the panel of some player. Immediately after, using BGA "this.slidetoObject" method, we make the disc slide to the "square" element, its final destination.

Note: don't forget to call the "play()", otherwise the token remains at its original location.

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.

Before we can show a token, we need to set the player colors in the setupNewGame function in reversi.game.php:
<pre>
$default_colors = array( "ffffff", "000000" );
</pre>

Now, to test if everything works fine, just call "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:

[[File:reversi3.jpg]]

== The database ==

We did most of the client-side programming, so let's have a look on the other side now.

To design the database model of our game, 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.

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.

[[File:reversi4.jpg]]

The database model of Reversi is very simple: just one table with the squares of the board. In our dbmodel.sql, we have this:

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

Now, a new database with a "board" table will be created each time we start a Reversi game. This is why after modifying our dbmodel.sql it's a good time to stop & start again our game.

== Setup the initial game position ==

The "setupNewGame" method of our reversi.game.php is called during initial setup: this is the place to initialize our data and to place the initial tokens on the board (initially, there are 4 tokens on the board).

Let's do this:

<pre>
// Init the board
$sql = "INSERT INTO board (board_x,board_y,board_player) VALUES ";
$sql_values = array();
list( $blackplayer_id, $whiteplayer_id ) = array_keys( $players );
for( $x=1; $x<=8; $x++ )
{
for( $y=1; $y<=8; $y++ )
{
$token_value = "NULL";
if( ($x==4 && $y==4) || ($x==5 && $y==5) ) // Initial positions of white player
$token_value = "'$whiteplayer_id'";
else if( ($x==4 && $y==5) || ($x==5 && $y==4) ) // Initial positions of black player
$token_value = "'$blackplayer_id'";

$sql_values[] = "('$x','$y',$token_value)";
}
}
$sql .= implode( $sql_values, ',' );
self::DbQuery( $sql );

// Active first player
self::activeNextPlayer();
</pre>

As you can see, we create one table entry for each square, with a "NULL" value which means "empty square". Of course, for 4 specific squares, we place an initial token.

At the end, we call activeNextPlayer to make the first player active at the beginning of the game.

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

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

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.

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:

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

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

As you can see, our "board" entry created in "getAllDatas" can be used here as "gamedatas.board" in our Javascript. We are using our previously developed "addTokenOnBoard" method.

Reload... and here we are:

[[File:reversi5.jpg]]

It starts to smell Reversi here...

== The game state machine ==

Now, let's stop our game again, because we are going to start the core game logic.

You already read the "Focus on BGA game state machine", so you know that this is the heart of your game logic. For reversi, it's very simple although. Here's a diagram of our game state machine:

[[File:reversi6.jpg]]

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

<pre>
$machinestates = array(

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

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

11 => array(
"name" => "nextPlayer",
"type" => "game",
"action" => "stNextPlayer",
"updateGameProgression" => true,
"transitions" => array( "nextTurn" => 10, "cantPlay" => 11, "endGame" => 99 )
),

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

);
</pre>

Now, let's create in reversi.game.php the methods that are declared in this game states description file:
* argPlayerTurn
* stNextPlayer

... and start a new Reversi game.

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

[[File:reversi7.jpg]]

== The rules ==

Now, what we would like to do is to indicate to the current player where it is allowed to play. The idea is to build a "getPossibleMoves" PHP method that return a list of coordinates where it is allowed to play. This method will be used in particular:
* As we just said, to help the player to see where he can play.
* When the player play, to check if he has the right to play here.

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

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.

If you want to look into details, please look at the "utility method" sections of reversi.game.php.

== Display allowed moves ==

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

To do this, we are using the "argPlayerTurn" method. This method is called each time we enter into "playerTurn" game state, and its result is transfered automatically to the client-side:

<pre>

function argPlayerTurn()
{
return array(
'possibleMoves' => self::getPossibleMoves( self::getActivePlayerId() )
);
}
</pre>

We are of course using the "getPossibleMoves" method we just developed.

Now, let's go to the client side to use the data returned by the method above. We are using the "onEnteringState" Javascript method that is called each time we enter into a new game state:

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

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

So, when we are entering into "playerTurn" game state, we are calling our "updatePossibleMoves" method. This method looks like this:

<pre>
updatePossibleMoves: function( possibleMoves )
{
// Remove current possible moves
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );

for( var x in possibleMoves )
{
for( var y in possibleMoves[ x ] )
{
// x,y is a possible move
dojo.addClass( 'square_'+x+'_'+y, 'possibleMove' );
}
}

this.addTooltipToClass( 'possibleMove', '', _('Place a disc here') );
},
</pre>

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

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

Then we loop through all possible moves our PHP "updatePossibleMoves" function created for us, and add the "possibleMove" class to each corresponding square.

Finally, we use the BGA framework "addTooltipToClass" method to associate a tooltip to all those highlighted squares so that players can understand their meaning.

And here we are:

[[File:reversi8.jpg.jpg]]

== Let's play ==

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

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

<pre>
dojo.query( '.square' ).connect( 'onclick', this, 'onPlayDisc' );
</pre>

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

Here's our "onPlayDisc" method below:

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

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

if( ! dojo.hasClass( 'square_'+x+'_'+y, 'possibleMove' ) )
{
// This is not a possible move => the click does nothing
return ;
}

if( this.checkAction( 'playDisc' ) ) // Check that this action is possible at this moment
{
this.ajaxcall( "/reversi/reversi/playDisc.html", {
x:x,
y:y
}, this, function( result ) {} );
}
},
</pre>

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

Now, we have to manage this "playDisc" action on server side. At first, we introduce a "playDisc" entry point in our "reversi.action.php":

<pre>
public function playDisc()
{
self::setAjaxMode();
$x = self::getArg( "x", AT_posint, true );
$y = self::getArg( "y", AT_posint, true );
$result = $this->game->playDisc( $x, $y );
self::ajaxResponse( );
}
</pre>

As you can see, we get the 2 arguments x and y from the javascript call, and call a corresponding "playDisc" method in our game logic.

Now, let's have a look of this playDisc method:

<pre>
function playDisc( $x, $y )
{
// Check that this player is active and that this action is possible at this moment
self::checkAction( 'playDisc' );
</pre>

... at first, we check that this action is possible according to current game state (see "possible action"). We already did it on client side, but it's important to do it on server side too (otherwise it would be possible to cheat).

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

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

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

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

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

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

self::DbQuery( $sql );

</pre>

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

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

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

</pre>

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

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

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

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

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

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

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

A last thing to do on the server side is to active the next player when we enter in the "nextPlayer" game state:

<pre>
function stNextPlayer()
{
// Active next player
$player_id = self::activeNextPlayer();

self::giveExtraTime( $player_id );
$this->gamestate->nextState( 'nextTurn' );

}
</pre>

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

[[File:reversi9.jpg]]

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

== Make the move appears automatically ==

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

In our "setupNotifications" method, we register 2 methods for the 2 notifications we created at the previous step ('playDisc' and 'turnOverDiscs'):

<pre>
dojo.subscribe( 'playDisc', this, "notif_playDisc" );
this.notifqueue.setSynchronous( 'playDisc', 500 );
dojo.subscribe( 'turnOverDiscs', this, "notif_turnOverDiscs" );
this.notifqueue.setSynchronous( 'turnOverDiscs', 1500 );
</pre>

As you can see, we associate our 2 notifications with 2 methods with the "notif_" prefix. At the same time, we define these notifications as "synchronous", with a duration in millisecond (500 for the first one, and 1500 for the second one). It tells the user interface to wait some time after executing the notification, to let the animation end before starting the next notification. In our specific case, the animation will be the following:
* Make a disc slide from the player panel to its place on the board
* (wait 500ms)
* Make all turned over discs blink (and of course turned them over)
* (wait 1500ms)
* Let the next player play.

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

<pre>
notif_playDisc: function( notif )
{
// Remove current possible moves (makes the board more clear)
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );

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

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

Now, here's the method that handle the turnOverDiscs notification:

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

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

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

// Remove any color class
dojo.removeClass( node, [ 'disccolor_000000', 'disccolor_ffffff' ] );
// ... and add the good one
dojo.addClass( node, 'disccolor_'+targetColor );

}
} ),
dojo.fadeIn( { node: 'disc_'+disc.x+''+disc.y } )

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

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

The list of the discs 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 it. The complete documentation on dojo animations [http://dojotoolkit.org/documentation/tutorials/1.6/animation/ can be found here].

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

Tutorial reversi

2012-12-06T12:08:18Z

Pikiou: /* Display allowed moves */ Missing the possibleMove class CSS declaration

== Introduction ==

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

Before you read this tutorial, you must:
* Read the overall presentations of the BGA Framework ([[Studio|see here]]).
* Know the [http://en.wikipedia.org/wiki/Reversi#Rules rules of Reversi].
* Know the languages used on BGA: PHP, SQL, HTML, CSS, Javascript.

== Create your first game ==

With the initial skeleton of code provided initially, you can already start a game from the BGA Studio. For now, we are going to work with 1 player only. Most of the time 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.

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

== Let it look like Reversi ==

It's always a good idea to start with a little bit of graphic work. Why? Because this helps to figure out how the final game will be, and issues that may appear later.

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

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

[[File:Board.jpg]]

Note that we are using a jpg file. Jpg are lighter than png, so faster to load. Later we are going to use PNGs for discs for transparency purpose.

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

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

* edit your reversi.css file to transform it into a visible board:

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

Refresh your page. Here's your board:

[[File:reversi1.jpg]]

== Make the squares appears ==

Now, what we need is to create some invisible HTML elements where squares are. These elements will be used as position references for width and black discs.
Obviously, we need 64 squares. To avoid writing 64 'div' elements on our template, we are going to use the "block" feature.

Let's modify our template like this:

<pre>
<div id="board">

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

</div>
</pre>

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.

Let's do it in our "reversi.view.php" file:

<pre>
$this->page->begin_block( "reversi_reversi", "square" );

$hor_scale = 64.8;
$ver_scale = 64.4;
for( $x=1; $x<=8; $x++ )
{
for( $y=1; $y<=8; $y++ )
{
$this->page->insert_block( "square", array(
'X' => $x,
'Y' => $y,
'LEFT' => round( ($x-1)*$hor_scale+10 ),
'TOP' => round( ($y-1)*$ver_scale+7 )
) );
}
}
</pre>

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.

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

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

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

Explanations:
* With "position: relative" on board, we ensure square elements are positioned relatively to board.
* For the test, we use a red background color for the square. This is a useful tip to figure out if everything is fine with invisible elements.

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

[[File:reversi2.jpg]]

== The discs ==

Now, our board is ready to receive some disc tokens!

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

<pre>


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

Then, let's introduce a new piece of art with the discs. We need some transparency here so we are using a png file:

[[File:tokens.png]]

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].

Now, let's separate the disc with some CSS stuff:

<pre>
.token {
width: 56px;
height: 56px;
position: absolute;
background-image: url('../../img/reversi/tokens.png');
}
.tokencolor_ffffff { background-position: 0px 0px; }
.tokencolor_000000 { background-position: -56px 0px; }
</pre>

With this CSS code, we apply the classes "token" and "tokencolor_ffffff" to a div element and we've got a white token. Yeah.

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

Now, let's make a first token appear on our board. Disc tokens are not visible at the beginning of the game: they appear dynamically during the game. For this reason, we are going to make them appear from our Javascript code, with a BGA Framework technique called "JS template".

In our template file (reversi_reversi.tpl), let's create the piece of HTML needed to display our token:

<pre>
<script type="text/javascript">

// Templates

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

</script>
</pre>

Note: we already created the "templates" section for you in the game skeleton.

As you can see, we defined a JS template named "jstpl_token" with a piece of HTML and two variables: the color of the token and its x/y coordinates. Note that the syntax of the argument is different for template block variables (brackets) and JS template variables (dollar and brackets).

Now, let's create a method in our Javascript code that will make a token appear on the board, using this template:

<pre>
addTokenOnBoard: function( x, y, player )
{
dojo.place( this.format_block( 'jstpl_token', {
x_y: x+'_'+y,
color: this.gamedatas.players[ player ].color
} ) , 'tokens' );

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

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.

Then, with BGA "this.placeOnObject" method, we place this element over the panel of some player. Immediately after, using BGA "this.slidetoObject" method, we make the disc slide to the "square" element, its final destination.

Note: don't forget to call the "play()", otherwise the token remains at its original location.

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.

Before we can show a token, we need to set the player colors in the setupNewGame function in reversi.game.php:
<pre>
$default_colors = array( "ffffff", "000000" );
</pre>

Now, to test if everything works fine, just call "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:

[[File:reversi3.jpg]]

== The database ==

We did most of the client-side programming, so let's have a look on the other side now.

To design the database model of our game, 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.

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.

[[File:reversi4.jpg]]

The database model of Reversi is very simple: just one table with the squares of the board. In our dbmodel.sql, we have this:

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

Now, a new database with a "board" table will be created each time we start a Reversi game. This is why after modifying our dbmodel.sql it's a good time to stop & start again our game.

== Setup the initial game position ==

The "setupNewGame" method of our reversi.game.php is called during initial setup: this is the place to initialize our data and to place the initial tokens on the board (initially, there are 4 tokens on the board).

Let's do this:

<pre>
// Init the board
$sql = "INSERT INTO board (board_x,board_y,board_player) VALUES ";
$sql_values = array();
list( $blackplayer_id, $whiteplayer_id ) = array_keys( $players );
for( $x=1; $x<=8; $x++ )
{
for( $y=1; $y<=8; $y++ )
{
$token_value = "NULL";
if( ($x==4 && $y==4) || ($x==5 && $y==5) ) // Initial positions of white player
$token_value = "'$whiteplayer_id'";
else if( ($x==4 && $y==5) || ($x==5 && $y==4) ) // Initial positions of black player
$token_value = "'$blackplayer_id'";

$sql_values[] = "('$x','$y',$token_value)";
}
}
$sql .= implode( $sql_values, ',' );
self::DbQuery( $sql );

// Active first player
self::activeNextPlayer();
</pre>

As you can see, we create one table entry for each square, with a "NULL" value which means "empty square". Of course, for 4 specific squares, we place an initial token.

At the end, we call activeNextPlayer to make the first player active at the beginning of the game.

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

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

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.

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:

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

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

As you can see, our "board" entry created in "getAllDatas" can be used here as "gamedatas.board" in our Javascript. We are using our previously developed "addTokenOnBoard" method.

Reload... and here we are:

[[File:reversi5.jpg]]

It starts to smell Reversi here...

== The game state machine ==

Now, let's stop our game again, because we are going to start the core game logic.

You already read the "Focus on BGA game state machine", so you know that this is the heart of your game logic. For reversi, it's very simple although. Here's a diagram of our game state machine:

[[File:reversi6.jpg]]

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

<pre>
$machinestates = array(

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

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

11 => array(
"name" => "nextPlayer",
"type" => "game",
"action" => "stNextPlayer",
"updateGameProgression" => true,
"transitions" => array( "nextTurn" => 10, "cantPlay" => 11, "endGame" => 99 )
),

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

);
</pre>

Now, let's create in reversi.game.php the methods that are declared in this game states description file:
* argPlayerTurn
* stNextPlayer

... and start a new Reversi game.

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

[[File:reversi7.jpg]]

== The rules ==

Now, what we would like to do is to indicate to the current player where it is allowed to play. The idea is to build a "getPossibleMoves" PHP method that return a list of coordinates where it is allowed to play. This method will be used in particular:
* As we just said, to help the player to see where he can play.
* When the player play, to check if he has the right to play here.

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

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.

If you want to look into details, please look at the "utility method" sections of reversi.game.php.

== Display allowed moves ==

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

To do this, we are using the "argPlayerTurn" method. This method is called each time we enter into "playerTurn" game state, and its result is transfered automatically to the client-side:

<pre>

function argPlayerTurn()
{
return array(
'possibleMoves' => self::getPossibleMoves( self::getActivePlayerId() )
);
}
</pre>

We are of course using the "getPossibleMoves" method we just developed.

Now, let's go to the client side to use the data returned by the method above. We are using the "onEnteringState" Javascript method that is called each time we enter into a new game state:

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

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

So, when we are entering into "playerTurn" game state, we are calling our "updatePossibleMoves" method. This method looks like this:

<pre>
updatePossibleMoves: function( possibleMoves )
{
// Remove current possible moves
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );

for( var x in possibleMoves )
{
for( var y in possibleMoves[ x ] )
{
// x,y is a possible move
dojo.addClass( 'square_'+x+'_'+y, 'possibleMove' );
}
}

this.addTooltipToClass( 'possibleMove', '', _('Place a disc here') );
},
</pre>

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

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

Then we loop through all possible moves that our PHP "updatePossibleMoves" create for us, and add the "possibleMove" class to corresponding square.

Finally, we use BGA framework "addTooltipToClass" method to associate a tooltip to all these highlighted squares in order players can understand the meaning of this.

And here we are:

[[File:reversi8.jpg.jpg]]

== Let's play ==

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

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

<pre>
dojo.query( '.square' ).connect( 'onclick', this, 'onPlayDisc' );
</pre>

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

Here's our "onPlayDisc" method below:

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

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

if( ! dojo.hasClass( 'square_'+x+'_'+y, 'possibleMove' ) )
{
// This is not a possible move => the click does nothing
return ;
}

if( this.checkAction( 'playDisc' ) ) // Check that this action is possible at this moment
{
this.ajaxcall( "/reversi/reversi/playDisc.html", {
x:x,
y:y
}, this, function( result ) {} );
}
},
</pre>

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

Now, we have to manage this "playDisc" action on server side. At first, we introduce a "playDisc" entry point in our "reversi.action.php":

<pre>
public function playDisc()
{
self::setAjaxMode();
$x = self::getArg( "x", AT_posint, true );
$y = self::getArg( "y", AT_posint, true );
$result = $this->game->playDisc( $x, $y );
self::ajaxResponse( );
}
</pre>

As you can see, we get the 2 arguments x and y from the javascript call, and call a corresponding "playDisc" method in our game logic.

Now, let's have a look of this playDisc method:

<pre>
function playDisc( $x, $y )
{
// Check that this player is active and that this action is possible at this moment
self::checkAction( 'playDisc' );
</pre>

... at first, we check that this action is possible according to current game state (see "possible action"). We already did it on client side, but it's important to do it on server side too (otherwise it would be possible to cheat).

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

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

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

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

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

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

self::DbQuery( $sql );

</pre>

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

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

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

</pre>

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

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

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

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

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

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

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

A last thing to do on the server side is to active the next player when we enter in the "nextPlayer" game state:

<pre>
function stNextPlayer()
{
// Active next player
$player_id = self::activeNextPlayer();

self::giveExtraTime( $player_id );
$this->gamestate->nextState( 'nextTurn' );

}
</pre>

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

[[File:reversi9.jpg]]

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

== Make the move appears automatically ==

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

In our "setupNotifications" method, we register 2 methods for the 2 notifications we created at the previous step ('playDisc' and 'turnOverDiscs'):

<pre>
dojo.subscribe( 'playDisc', this, "notif_playDisc" );
this.notifqueue.setSynchronous( 'playDisc', 500 );
dojo.subscribe( 'turnOverDiscs', this, "notif_turnOverDiscs" );
this.notifqueue.setSynchronous( 'turnOverDiscs', 1500 );
</pre>

As you can see, we associate our 2 notifications with 2 methods with the "notif_" prefix. At the same time, we define these notifications as "synchronous", with a duration in millisecond (500 for the first one, and 1500 for the second one). It tells the user interface to wait some time after executing the notification, to let the animation end before starting the next notification. In our specific case, the animation will be the following:
* Make a disc slide from the player panel to its place on the board
* (wait 500ms)
* Make all turned over discs blink (and of course turned them over)
* (wait 1500ms)
* Let the next player play.

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

<pre>
notif_playDisc: function( notif )
{
// Remove current possible moves (makes the board more clear)
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );

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

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

Now, here's the method that handle the turnOverDiscs notification:

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

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

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

// Remove any color class
dojo.removeClass( node, [ 'disccolor_000000', 'disccolor_ffffff' ] );
// ... and add the good one
dojo.addClass( node, 'disccolor_'+targetColor );

}
} ),
dojo.fadeIn( { node: 'disc_'+disc.x+''+disc.y } )

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

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

The list of the discs 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 it. The complete documentation on dojo animations [http://dojotoolkit.org/documentation/tutorials/1.6/animation/ can be found here].

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

Tutorial reversi

2012-12-06T02:07:54Z

Pikiou: /* The game state machine */ Typos

== Introduction ==

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

Before you read this tutorial, you must:
* Read the overall presentations of the BGA Framework ([[Studio|see here]]).
* Know the [http://en.wikipedia.org/wiki/Reversi#Rules rules of Reversi].
* Know the languages used on BGA: PHP, SQL, HTML, CSS, Javascript.

== Create your first game ==

With the initial skeleton of code provided initially, you can already start a game from the BGA Studio. For now, we are going to work with 1 player only. Most of the time 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.

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

== Let it look like Reversi ==

It's always a good idea to start with a little bit of graphic work. Why? Because this helps to figure out how the final game will be, and issues that may appear later.

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

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

[[File:Board.jpg]]

Note that we are using a jpg file. Jpg are lighter than png, so faster to load. Later we are going to use PNGs for discs for transparency purpose.

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

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

* edit your reversi.css file to transform it into a visible board:

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

Refresh your page. Here's your board:

[[File:reversi1.jpg]]

== Make the squares appears ==

Now, what we need is to create some invisible HTML elements where squares are. These elements will be used as position references for width and black discs.
Obviously, we need 64 squares. To avoid writing 64 'div' elements on our template, we are going to use the "block" feature.

Let's modify our template like this:

<pre>
<div id="board">

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

</div>
</pre>

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.

Let's do it in our "reversi.view.php" file:

<pre>
$this->page->begin_block( "reversi_reversi", "square" );

$hor_scale = 64.8;
$ver_scale = 64.4;
for( $x=1; $x<=8; $x++ )
{
for( $y=1; $y<=8; $y++ )
{
$this->page->insert_block( "square", array(
'X' => $x,
'Y' => $y,
'LEFT' => round( ($x-1)*$hor_scale+10 ),
'TOP' => round( ($y-1)*$ver_scale+7 )
) );
}
}
</pre>

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.

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

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

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

Explanations:
* With "position: relative" on board, we ensure square elements are positioned relatively to board.
* For the test, we use a red background color for the square. This is a useful tip to figure out if everything is fine with invisible elements.

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

[[File:reversi2.jpg]]

== The discs ==

Now, our board is ready to receive some disc tokens!

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

<pre>


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

Then, let's introduce a new piece of art with the discs. We need some transparency here so we are using a png file:

[[File:tokens.png]]

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].

Now, let's separate the disc with some CSS stuff:

<pre>
.token {
width: 56px;
height: 56px;
position: absolute;
background-image: url('../../img/reversi/tokens.png');
}
.tokencolor_ffffff { background-position: 0px 0px; }
.tokencolor_000000 { background-position: -56px 0px; }
</pre>

With this CSS code, we apply the classes "token" and "tokencolor_ffffff" to a div element and we've got a white token. Yeah.

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

Now, let's make a first token appear on our board. Disc tokens are not visible at the beginning of the game: they appear dynamically during the game. For this reason, we are going to make them appear from our Javascript code, with a BGA Framework technique called "JS template".

In our template file (reversi_reversi.tpl), let's create the piece of HTML needed to display our token:

<pre>
<script type="text/javascript">

// Templates

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

</script>
</pre>

Note: we already created the "templates" section for you in the game skeleton.

As you can see, we defined a JS template named "jstpl_token" with a piece of HTML and two variables: the color of the token and its x/y coordinates. Note that the syntax of the argument is different for template block variables (brackets) and JS template variables (dollar and brackets).

Now, let's create a method in our Javascript code that will make a token appear on the board, using this template:

<pre>
addTokenOnBoard: function( x, y, player )
{
dojo.place( this.format_block( 'jstpl_token', {
x_y: x+'_'+y,
color: this.gamedatas.players[ player ].color
} ) , 'tokens' );

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

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.

Then, with BGA "this.placeOnObject" method, we place this element over the panel of some player. Immediately after, using BGA "this.slidetoObject" method, we make the disc slide to the "square" element, its final destination.

Note: don't forget to call the "play()", otherwise the token remains at its original location.

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.

Before we can show a token, we need to set the player colors in the setupNewGame function in reversi.game.php:
<pre>
$default_colors = array( "ffffff", "000000" );
</pre>

Now, to test if everything works fine, just call "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:

[[File:reversi3.jpg]]

== The database ==

We did most of the client-side programming, so let's have a look on the other side now.

To design the database model of our game, 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.

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.

[[File:reversi4.jpg]]

The database model of Reversi is very simple: just one table with the squares of the board. In our dbmodel.sql, we have this:

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

Now, a new database with a "board" table will be created each time we start a Reversi game. This is why after modifying our dbmodel.sql it's a good time to stop & start again our game.

== Setup the initial game position ==

The "setupNewGame" method of our reversi.game.php is called during initial setup: this is the place to initialize our data and to place the initial tokens on the board (initially, there are 4 tokens on the board).

Let's do this:

<pre>
// Init the board
$sql = "INSERT INTO board (board_x,board_y,board_player) VALUES ";
$sql_values = array();
list( $blackplayer_id, $whiteplayer_id ) = array_keys( $players );
for( $x=1; $x<=8; $x++ )
{
for( $y=1; $y<=8; $y++ )
{
$token_value = "NULL";
if( ($x==4 && $y==4) || ($x==5 && $y==5) ) // Initial positions of white player
$token_value = "'$whiteplayer_id'";
else if( ($x==4 && $y==5) || ($x==5 && $y==4) ) // Initial positions of black player
$token_value = "'$blackplayer_id'";

$sql_values[] = "('$x','$y',$token_value)";
}
}
$sql .= implode( $sql_values, ',' );
self::DbQuery( $sql );

// Active first player
self::activeNextPlayer();
</pre>

As you can see, we create one table entry for each square, with a "NULL" value which means "empty square". Of course, for 4 specific squares, we place an initial token.

At the end, we call activeNextPlayer to make the first player active at the beginning of the game.

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

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

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.

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:

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

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

As you can see, our "board" entry created in "getAllDatas" can be used here as "gamedatas.board" in our Javascript. We are using our previously developed "addTokenOnBoard" method.

Reload... and here we are:

[[File:reversi5.jpg]]

It starts to smell Reversi here...

== The game state machine ==

Now, let's stop our game again, because we are going to start the core game logic.

You already read the "Focus on BGA game state machine", so you know that this is the heart of your game logic. For reversi, it's very simple although. Here's a diagram of our game state machine:

[[File:reversi6.jpg]]

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

<pre>
$machinestates = array(

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

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

11 => array(
"name" => "nextPlayer",
"type" => "game",
"action" => "stNextPlayer",
"updateGameProgression" => true,
"transitions" => array( "nextTurn" => 10, "cantPlay" => 11, "endGame" => 99 )
),

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

);
</pre>

Now, let's create in reversi.game.php the methods that are declared in this game states description file:
* argPlayerTurn
* stNextPlayer

... and start a new Reversi game.

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

[[File:reversi7.jpg]]

== The rules ==

Now, what we would like to do is to indicate to the current player where it is allowed to play. The idea is to build a "getPossibleMoves" PHP method that return a list of coordinates where it is allowed to play. This method will be used in particular:
* As we just said, to help the player to see where he can play.
* When the player play, to check if he has the right to play here.

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

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.

If you want to look into details, please look at the "utility method" sections of reversi.game.php.

== Display allowed moves ==

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

To do this, we are using the "argPlayerTurn" method. This method is called each time we enter into "playerTurn" game state, and its result is transfered automatically to the client-side:

<pre>

function argPlayerTurn()
{
return array(
'possibleMoves' => self::getPossibleMoves( self::getActivePlayerId() )
);
}
</pre>

We are of course using the "getPossibleMoves" method we just developed.

Now, let's go to the client side to use the data returned by the method above. We are using the "onEnteringState" Javascript method that is called each time we enter into a new game state:

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

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

So, when we are entering into "playerTurn" game state, we are calling our "updatePossibleMoves" method. This method looks like this:

<pre>
updatePossibleMoves: function( possibleMoves )
{
// Remove current possible moves
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );

for( var x in possibleMoves )
{
for( var y in possibleMoves[ x ] )
{
// x,y is a possible move
dojo.addClass( 'square_'+x+'_'+y, 'possibleMove' );
}
}

this.addTooltipToClass( 'possibleMove', '', _('Place a disc here') );
},
</pre>

The idea here is that we've created a CSS class ("possibleMove") that can be applied to a "square" element to highlight it.

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

Then we loop through all possible moves that our PHP "updatePossibleMoves" create for us, and add the "possibleMove" class to corresponding square.

Finally, we use BGA framework "addTooltipToClass" method to associate a tooltip to all these highlighted squares in order players can understand the meaning of this.

And here we are:

[[File:reversi8.jpg.jpg]]

== Let's play ==

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

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

<pre>
dojo.query( '.square' ).connect( 'onclick', this, 'onPlayDisc' );
</pre>

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

Here's our "onPlayDisc" method below:

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

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

if( ! dojo.hasClass( 'square_'+x+'_'+y, 'possibleMove' ) )
{
// This is not a possible move => the click does nothing
return ;
}

if( this.checkAction( 'playDisc' ) ) // Check that this action is possible at this moment
{
this.ajaxcall( "/reversi/reversi/playDisc.html", {
x:x,
y:y
}, this, function( result ) {} );
}
},
</pre>

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

Now, we have to manage this "playDisc" action on server side. At first, we introduce a "playDisc" entry point in our "reversi.action.php":

<pre>
public function playDisc()
{
self::setAjaxMode();
$x = self::getArg( "x", AT_posint, true );
$y = self::getArg( "y", AT_posint, true );
$result = $this->game->playDisc( $x, $y );
self::ajaxResponse( );
}
</pre>

As you can see, we get the 2 arguments x and y from the javascript call, and call a corresponding "playDisc" method in our game logic.

Now, let's have a look of this playDisc method:

<pre>
function playDisc( $x, $y )
{
// Check that this player is active and that this action is possible at this moment
self::checkAction( 'playDisc' );
</pre>

... at first, we check that this action is possible according to current game state (see "possible action"). We already did it on client side, but it's important to do it on server side too (otherwise it would be possible to cheat).

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

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

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

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

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

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

self::DbQuery( $sql );

</pre>

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

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

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

</pre>

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

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

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

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

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

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

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

A last thing to do on the server side is to active the next player when we enter in the "nextPlayer" game state:

<pre>
function stNextPlayer()
{
// Active next player
$player_id = self::activeNextPlayer();

self::giveExtraTime( $player_id );
$this->gamestate->nextState( 'nextTurn' );

}
</pre>

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

[[File:reversi9.jpg]]

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

== Make the move appears automatically ==

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

In our "setupNotifications" method, we register 2 methods for the 2 notifications we created at the previous step ('playDisc' and 'turnOverDiscs'):

<pre>
dojo.subscribe( 'playDisc', this, "notif_playDisc" );
this.notifqueue.setSynchronous( 'playDisc', 500 );
dojo.subscribe( 'turnOverDiscs', this, "notif_turnOverDiscs" );
this.notifqueue.setSynchronous( 'turnOverDiscs', 1500 );
</pre>

As you can see, we associate our 2 notifications with 2 methods with the "notif_" prefix. At the same time, we define these notifications as "synchronous", with a duration in millisecond (500 for the first one, and 1500 for the second one). It tells the user interface to wait some time after executing the notification, to let the animation end before starting the next notification. In our specific case, the animation will be the following:
* Make a disc slide from the player panel to its place on the board
* (wait 500ms)
* Make all turned over discs blink (and of course turned them over)
* (wait 1500ms)
* Let the next player play.

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

<pre>
notif_playDisc: function( notif )
{
// Remove current possible moves (makes the board more clear)
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );

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

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

Now, here's the method that handle the turnOverDiscs notification:

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

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

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

// Remove any color class
dojo.removeClass( node, [ 'disccolor_000000', 'disccolor_ffffff' ] );
// ... and add the good one
dojo.addClass( node, 'disccolor_'+targetColor );

}
} ),
dojo.fadeIn( { node: 'disc_'+disc.x+''+disc.y } )

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

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

The list of the discs 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 it. The complete documentation on dojo animations [http://dojotoolkit.org/documentation/tutorials/1.6/animation/ can be found here].

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

Tutorial reversi

2012-12-06T01:20:35Z

Pikiou: /* The discs */ Set player colors to white and black

== Introduction ==

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

Before you read this tutorial, you must:
* Read the overall presentations of the BGA Framework ([[Studio|see here]]).
* Know the [http://en.wikipedia.org/wiki/Reversi#Rules rules of Reversi].
* Know the languages used on BGA: PHP, SQL, HTML, CSS, Javascript.

== Create your first game ==

With the initial skeleton of code provided initially, you can already start a game from the BGA Studio. For now, we are going to work with 1 player only. Most of the time 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.

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

== Let it look like Reversi ==

It's always a good idea to start with a little bit of graphic work. Why? Because this helps to figure out how the final game will be, and issues that may appear later.

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

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

[[File:Board.jpg]]

Note that we are using a jpg file. Jpg are lighter than png, so faster to load. Later we are going to use PNGs for discs for transparency purpose.

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

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

* edit your reversi.css file to transform it into a visible board:

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

Refresh your page. Here's your board:

[[File:reversi1.jpg]]

== Make the squares appears ==

Now, what we need is to create some invisible HTML elements where squares are. These elements will be used as position references for width and black discs.
Obviously, we need 64 squares. To avoid writing 64 'div' elements on our template, we are going to use the "block" feature.

Let's modify our template like this:

<pre>
<div id="board">

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

</div>
</pre>

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.

Let's do it in our "reversi.view.php" file:

<pre>
$this->page->begin_block( "reversi_reversi", "square" );

$hor_scale = 64.8;
$ver_scale = 64.4;
for( $x=1; $x<=8; $x++ )
{
for( $y=1; $y<=8; $y++ )
{
$this->page->insert_block( "square", array(
'X' => $x,
'Y' => $y,
'LEFT' => round( ($x-1)*$hor_scale+10 ),
'TOP' => round( ($y-1)*$ver_scale+7 )
) );
}
}
</pre>

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.

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

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

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

Explanations:
* With "position: relative" on board, we ensure square elements are positioned relatively to board.
* For the test, we use a red background color for the square. This is a useful tip to figure out if everything is fine with invisible elements.

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

[[File:reversi2.jpg]]

== The discs ==

Now, our board is ready to receive some disc tokens!

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

<pre>


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

Then, let's introduce a new piece of art with the discs. We need some transparency here so we are using a png file:

[[File:tokens.png]]

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].

Now, let's separate the disc with some CSS stuff:

<pre>
.token {
width: 56px;
height: 56px;
position: absolute;
background-image: url('../../img/reversi/tokens.png');
}
.tokencolor_ffffff { background-position: 0px 0px; }
.tokencolor_000000 { background-position: -56px 0px; }
</pre>

With this CSS code, we apply the classes "token" and "tokencolor_ffffff" to a div element and we've got a white token. Yeah.

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

Now, let's make a first token appear on our board. Disc tokens are not visible at the beginning of the game: they appear dynamically during the game. For this reason, we are going to make them appear from our Javascript code, with a BGA Framework technique called "JS template".

In our template file (reversi_reversi.tpl), let's create the piece of HTML needed to display our token:

<pre>
<script type="text/javascript">

// Templates

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

</script>
</pre>

Note: we already created the "templates" section for you in the game skeleton.

As you can see, we defined a JS template named "jstpl_token" with a piece of HTML and two variables: the color of the token and its x/y coordinates. Note that the syntax of the argument is different for template block variables (brackets) and JS template variables (dollar and brackets).

Now, let's create a method in our Javascript code that will make a token appear on the board, using this template:

<pre>
addTokenOnBoard: function( x, y, player )
{
dojo.place( this.format_block( 'jstpl_token', {
x_y: x+'_'+y,
color: this.gamedatas.players[ player ].color
} ) , 'tokens' );

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

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.

Then, with BGA "this.placeOnObject" method, we place this element over the panel of some player. Immediately after, using BGA "this.slidetoObject" method, we make the disc slide to the "square" element, its final destination.

Note: don't forget to call the "play()", otherwise the token remains at its original location.

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.

Before we can show a token, we need to set the player colors in the setupNewGame function in reversi.game.php:
<pre>
$default_colors = array( "ffffff", "000000" );
</pre>

Now, to test if everything works fine, just call "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:

[[File:reversi3.jpg]]

== The database ==

We did most of the client-side programming, so let's have a look on the other side now.

To design the database model of our game, 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.

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.

[[File:reversi4.jpg]]

The database model of Reversi is very simple: just one table with the squares of the board. In our dbmodel.sql, we have this:

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

Now, a new database with a "board" table will be created each time we start a Reversi game. This is why after modifying our dbmodel.sql it's a good time to stop & start again our game.

== Setup the initial game position ==

The "setupNewGame" method of our reversi.game.php is called during initial setup: this is the place to initialize our data and to place the initial tokens on the board (initially, there are 4 tokens on the board).

Let's do this:

<pre>
// Init the board
$sql = "INSERT INTO board (board_x,board_y,board_player) VALUES ";
$sql_values = array();
list( $blackplayer_id, $whiteplayer_id ) = array_keys( $players );
for( $x=1; $x<=8; $x++ )
{
for( $y=1; $y<=8; $y++ )
{
$token_value = "NULL";
if( ($x==4 && $y==4) || ($x==5 && $y==5) ) // Initial positions of white player
$token_value = "'$whiteplayer_id'";
else if( ($x==4 && $y==5) || ($x==5 && $y==4) ) // Initial positions of black player
$token_value = "'$blackplayer_id'";

$sql_values[] = "('$x','$y',$token_value)";
}
}
$sql .= implode( $sql_values, ',' );
self::DbQuery( $sql );

// Active first player
self::activeNextPlayer();
</pre>

As you can see, we create one table entry for each square, with a "NULL" value which means "empty square". Of course, for 4 specific squares, we place an initial token.

At the end, we call activeNextPlayer to make the first player active at the beginning of the game.

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

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

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.

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:

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

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

As you can see, our "board" entry created in "getAllDatas" can be used here as "gamedatas.board" in our Javascript. We are using our previously developed "addTokenOnBoard" method.

Reload... and here we are:

[[File:reversi5.jpg]]

It starts to smell Reversi here...

== The game state machine ==

Now, let's stop our game again, because we are going to start the core game logic.

You already read the "Focus on BGA game state machine", so you know that this is the heart of your game logic. For reversi game, it's very simple although. Here's a diagram of our game state machine for Reversi:

[[File:reversi6.jpg]]

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

<pre>
$machinestates = array(

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

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

11 => array(
"name" => "nextPlayer",
"type" => "game",
"action" => "stNextPlayer",
"updateGameProgression" => true,
"transitions" => array( "nextTurn" => 10, "cantPlay" => 11, "endGame" => 99 )
),

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

);
</pre>

Now, let's create in our reversi.game.php file the methods that are declared in this game states description file:
* argPlayerTurn
* stNextPlayer

... and start a new Reversi game.

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

[[File:reversi7.jpg]]

== The rules ==

Now, what we would like to do is to indicate to the current player where it is allowed to play. The idea is to build a "getPossibleMoves" PHP method that return a list of coordinates where it is allowed to play. This method will be used in particular:
* As we just said, to help the player to see where he can play.
* When the player play, to check if he has the right to play here.

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

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.

If you want to look into details, please look at the "utility method" sections of reversi.game.php.

== Display allowed moves ==

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

To do this, we are using the "argPlayerTurn" method. This method is called each time we enter into "playerTurn" game state, and its result is transfered automatically to the client-side:

<pre>

function argPlayerTurn()
{
return array(
'possibleMoves' => self::getPossibleMoves( self::getActivePlayerId() )
);
}
</pre>

We are of course using the "getPossibleMoves" method we just developed.

Now, let's go to the client side to use the data returned by the method above. We are using the "onEnteringState" Javascript method that is called each time we enter into a new game state:

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

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

So, when we are entering into "playerTurn" game state, we are calling our "updatePossibleMoves" method. This method looks like this:

<pre>
updatePossibleMoves: function( possibleMoves )
{
// Remove current possible moves
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );

for( var x in possibleMoves )
{
for( var y in possibleMoves[ x ] )
{
// x,y is a possible move
dojo.addClass( 'square_'+x+'_'+y, 'possibleMove' );
}
}

this.addTooltipToClass( 'possibleMove', '', _('Place a disc here') );
},
</pre>

The idea here is that we've created a CSS class ("possibleMove") that can be applied to a "square" element to highlight it.

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

Then we loop through all possible moves that our PHP "updatePossibleMoves" create for us, and add the "possibleMove" class to corresponding square.

Finally, we use BGA framework "addTooltipToClass" method to associate a tooltip to all these highlighted squares in order players can understand the meaning of this.

And here we are:

[[File:reversi8.jpg.jpg]]

== Let's play ==

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

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

<pre>
dojo.query( '.square' ).connect( 'onclick', this, 'onPlayDisc' );
</pre>

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

Here's our "onPlayDisc" method below:

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

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

if( ! dojo.hasClass( 'square_'+x+'_'+y, 'possibleMove' ) )
{
// This is not a possible move => the click does nothing
return ;
}

if( this.checkAction( 'playDisc' ) ) // Check that this action is possible at this moment
{
this.ajaxcall( "/reversi/reversi/playDisc.html", {
x:x,
y:y
}, this, function( result ) {} );
}
},
</pre>

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

Now, we have to manage this "playDisc" action on server side. At first, we introduce a "playDisc" entry point in our "reversi.action.php":

<pre>
public function playDisc()
{
self::setAjaxMode();
$x = self::getArg( "x", AT_posint, true );
$y = self::getArg( "y", AT_posint, true );
$result = $this->game->playDisc( $x, $y );
self::ajaxResponse( );
}
</pre>

As you can see, we get the 2 arguments x and y from the javascript call, and call a corresponding "playDisc" method in our game logic.

Now, let's have a look of this playDisc method:

<pre>
function playDisc( $x, $y )
{
// Check that this player is active and that this action is possible at this moment
self::checkAction( 'playDisc' );
</pre>

... at first, we check that this action is possible according to current game state (see "possible action"). We already did it on client side, but it's important to do it on server side too (otherwise it would be possible to cheat).

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

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

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

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

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

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

self::DbQuery( $sql );

</pre>

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

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

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

</pre>

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

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

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

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

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

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

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

A last thing to do on the server side is to active the next player when we enter in the "nextPlayer" game state:

<pre>
function stNextPlayer()
{
// Active next player
$player_id = self::activeNextPlayer();

self::giveExtraTime( $player_id );
$this->gamestate->nextState( 'nextTurn' );

}
</pre>

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

[[File:reversi9.jpg]]

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

== Make the move appears automatically ==

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

In our "setupNotifications" method, we register 2 methods for the 2 notifications we created at the previous step ('playDisc' and 'turnOverDiscs'):

<pre>
dojo.subscribe( 'playDisc', this, "notif_playDisc" );
this.notifqueue.setSynchronous( 'playDisc', 500 );
dojo.subscribe( 'turnOverDiscs', this, "notif_turnOverDiscs" );
this.notifqueue.setSynchronous( 'turnOverDiscs', 1500 );
</pre>

As you can see, we associate our 2 notifications with 2 methods with the "notif_" prefix. At the same time, we define these notifications as "synchronous", with a duration in millisecond (500 for the first one, and 1500 for the second one). It tells the user interface to wait some time after executing the notification, to let the animation end before starting the next notification. In our specific case, the animation will be the following:
* Make a disc slide from the player panel to its place on the board
* (wait 500ms)
* Make all turned over discs blink (and of course turned them over)
* (wait 1500ms)
* Let the next player play.

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

<pre>
notif_playDisc: function( notif )
{
// Remove current possible moves (makes the board more clear)
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );

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

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

Now, here's the method that handle the turnOverDiscs notification:

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

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

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

// Remove any color class
dojo.removeClass( node, [ 'disccolor_000000', 'disccolor_ffffff' ] );
// ... and add the good one
dojo.addClass( node, 'disccolor_'+targetColor );

}
} ),
dojo.fadeIn( { node: 'disc_'+disc.x+''+disc.y } )

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

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

The list of the discs 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 it. The complete documentation on dojo animations [http://dojotoolkit.org/documentation/tutorials/1.6/animation/ can be found here].

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

Tutorial reversi

2012-12-06T01:12:25Z

Pikiou: /* Setup the initial game position */ $blackplayer_id and $whiteplayer_id weren't defined

== Introduction ==

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

Before you read this tutorial, you must:
* Read the overall presentations of the BGA Framework ([[Studio|see here]]).
* Know the [http://en.wikipedia.org/wiki/Reversi#Rules rules of Reversi].
* Know the languages used on BGA: PHP, SQL, HTML, CSS, Javascript.

== Create your first game ==

With the initial skeleton of code provided initially, you can already start a game from the BGA Studio. For now, we are going to work with 1 player only. Most of the time 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.

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

== Let it look like Reversi ==

It's always a good idea to start with a little bit of graphic work. Why? Because this helps to figure out how the final game will be, and issues that may appear later.

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

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

[[File:Board.jpg]]

Note that we are using a jpg file. Jpg are lighter than png, so faster to load. Later we are going to use PNGs for discs for transparency purpose.

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

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

* edit your reversi.css file to transform it into a visible board:

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

Refresh your page. Here's your board:

[[File:reversi1.jpg]]

== Make the squares appears ==

Now, what we need is to create some invisible HTML elements where squares are. These elements will be used as position references for width and black discs.
Obviously, we need 64 squares. To avoid writing 64 'div' elements on our template, we are going to use the "block" feature.

Let's modify our template like this:

<pre>
<div id="board">

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

</div>
</pre>

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.

Let's do it in our "reversi.view.php" file:

<pre>
$this->page->begin_block( "reversi_reversi", "square" );

$hor_scale = 64.8;
$ver_scale = 64.4;
for( $x=1; $x<=8; $x++ )
{
for( $y=1; $y<=8; $y++ )
{
$this->page->insert_block( "square", array(
'X' => $x,
'Y' => $y,
'LEFT' => round( ($x-1)*$hor_scale+10 ),
'TOP' => round( ($y-1)*$ver_scale+7 )
) );
}
}
</pre>

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.

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

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

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

Explanations:
* With "position: relative" on board, we ensure square elements are positioned relatively to board.
* For the test, we use a red background color for the square. This is a useful tip to figure out if everything is fine with invisible elements.

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

[[File:reversi2.jpg]]

== The discs ==

Now, our board is ready to receive some disc tokens!

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

<pre>


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

Then, let's introduce a new piece of art with the discs. We need some transparency here so we are using a png file:

[[File:tokens.png]]

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].

Now, let's separate the disc with some CSS stuff:

<pre>
.token {
width: 56px;
height: 56px;
position: absolute;
background-image: url('../../img/reversi/tokens.png');
}
.tokencolor_ffffff { background-position: 0px 0px; }
.tokencolor_000000 { background-position: -56px 0px; }
</pre>

With this CSS code, we apply the classes "token" and "tokencolor_ffffff" to a div element and we've got a white token. Yeah.

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

Now, let's make a first token appear on our board. Disc tokens are not visible at the beginning of the game: they appear dynamically during the game. For this reason, we are going to make them appear from our Javascript code, with a BGA Framework technique called "JS template".

In our template file (reversi_reversi.tpl), let's create the piece of HTML needed to display our token:

<pre>
<script type="text/javascript">

// Templates

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

</script>
</pre>

Note: we already created the "templates" section for you in the game skeleton.

As you can see, we defined a JS template named "jstpl_token" with a piece of HTML and two variables: the color of the token and its x/y coordinates. Note that the syntax of the argument is different for template block variables (brackets) and JS template variables (dollar and brackets).

Now, let's create a method in our Javascript code that will make a token appear on the board, using this template:

<pre>
addTokenOnBoard: function( x, y, player )
{
dojo.place( this.format_block( 'jstpl_token', {
x_y: x+'_'+y,
color: this.gamedatas.players[ player ].color
} ) , 'tokens' );

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

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.

Then, with BGA "this.placeOnObject" method, we place this element over the panel of some player. Immediately after, using BGA "this.slidetoObject" method, we make the disc slide to the "square" element, its final destination.

Note: don't forget to call the "play()", otherwise the token remains at its original location.

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.

Now, to test if everything works fine, just call "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:

[[File:reversi3.jpg]]

== The database ==

We did most of the client-side programming, so let's have a look on the other side now.

To design the database model of our game, 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.

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.

[[File:reversi4.jpg]]

The database model of Reversi is very simple: just one table with the squares of the board. In our dbmodel.sql, we have this:

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

Now, a new database with a "board" table will be created each time we start a Reversi game. This is why after modifying our dbmodel.sql it's a good time to stop & start again our game.

== Setup the initial game position ==

The "setupNewGame" method of our reversi.game.php is called during initial setup: this is the place to initialize our data and to place the initial tokens on the board (initially, there are 4 tokens on the board).

Let's do this:

<pre>
// Init the board
$sql = "INSERT INTO board (board_x,board_y,board_player) VALUES ";
$sql_values = array();
list( $blackplayer_id, $whiteplayer_id ) = array_keys( $players );
for( $x=1; $x<=8; $x++ )
{
for( $y=1; $y<=8; $y++ )
{
$token_value = "NULL";
if( ($x==4 && $y==4) || ($x==5 && $y==5) ) // Initial positions of white player
$token_value = "'$whiteplayer_id'";
else if( ($x==4 && $y==5) || ($x==5 && $y==4) ) // Initial positions of black player
$token_value = "'$blackplayer_id'";

$sql_values[] = "('$x','$y',$token_value)";
}
}
$sql .= implode( $sql_values, ',' );
self::DbQuery( $sql );

// Active first player
self::activeNextPlayer();
</pre>

As you can see, we create one table entry for each square, with a "NULL" value which means "empty square". Of course, for 4 specific squares, we place an initial token.

At the end, we call activeNextPlayer to make the first player active at the beginning of the game.

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

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

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.

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:

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

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

As you can see, our "board" entry created in "getAllDatas" can be used here as "gamedatas.board" in our Javascript. We are using our previously developed "addTokenOnBoard" method.

Reload... and here we are:

[[File:reversi5.jpg]]

It starts to smell Reversi here...

== The game state machine ==

Now, let's stop our game again, because we are going to start the core game logic.

You already read the "Focus on BGA game state machine", so you know that this is the heart of your game logic. For reversi game, it's very simple although. Here's a diagram of our game state machine for Reversi:

[[File:reversi6.jpg]]

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

<pre>
$machinestates = array(

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

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

11 => array(
"name" => "nextPlayer",
"type" => "game",
"action" => "stNextPlayer",
"updateGameProgression" => true,
"transitions" => array( "nextTurn" => 10, "cantPlay" => 11, "endGame" => 99 )
),

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

);
</pre>

Now, let's create in our reversi.game.php file the methods that are declared in this game states description file:
* argPlayerTurn
* stNextPlayer

... and start a new Reversi game.

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

[[File:reversi7.jpg]]

== The rules ==

Now, what we would like to do is to indicate to the current player where it is allowed to play. The idea is to build a "getPossibleMoves" PHP method that return a list of coordinates where it is allowed to play. This method will be used in particular:
* As we just said, to help the player to see where he can play.
* When the player play, to check if he has the right to play here.

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

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.

If you want to look into details, please look at the "utility method" sections of reversi.game.php.

== Display allowed moves ==

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

To do this, we are using the "argPlayerTurn" method. This method is called each time we enter into "playerTurn" game state, and its result is transfered automatically to the client-side:

<pre>

function argPlayerTurn()
{
return array(
'possibleMoves' => self::getPossibleMoves( self::getActivePlayerId() )
);
}
</pre>

We are of course using the "getPossibleMoves" method we just developed.

Now, let's go to the client side to use the data returned by the method above. We are using the "onEnteringState" Javascript method that is called each time we enter into a new game state:

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

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

So, when we are entering into "playerTurn" game state, we are calling our "updatePossibleMoves" method. This method looks like this:

<pre>
updatePossibleMoves: function( possibleMoves )
{
// Remove current possible moves
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );

for( var x in possibleMoves )
{
for( var y in possibleMoves[ x ] )
{
// x,y is a possible move
dojo.addClass( 'square_'+x+'_'+y, 'possibleMove' );
}
}

this.addTooltipToClass( 'possibleMove', '', _('Place a disc here') );
},
</pre>

The idea here is that we've created a CSS class ("possibleMove") that can be applied to a "square" element to highlight it.

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

Then we loop through all possible moves that our PHP "updatePossibleMoves" create for us, and add the "possibleMove" class to corresponding square.

Finally, we use BGA framework "addTooltipToClass" method to associate a tooltip to all these highlighted squares in order players can understand the meaning of this.

And here we are:

[[File:reversi8.jpg.jpg]]

== Let's play ==

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

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

<pre>
dojo.query( '.square' ).connect( 'onclick', this, 'onPlayDisc' );
</pre>

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

Here's our "onPlayDisc" method below:

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

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

if( ! dojo.hasClass( 'square_'+x+'_'+y, 'possibleMove' ) )
{
// This is not a possible move => the click does nothing
return ;
}

if( this.checkAction( 'playDisc' ) ) // Check that this action is possible at this moment
{
this.ajaxcall( "/reversi/reversi/playDisc.html", {
x:x,
y:y
}, this, function( result ) {} );
}
},
</pre>

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

Now, we have to manage this "playDisc" action on server side. At first, we introduce a "playDisc" entry point in our "reversi.action.php":

<pre>
public function playDisc()
{
self::setAjaxMode();
$x = self::getArg( "x", AT_posint, true );
$y = self::getArg( "y", AT_posint, true );
$result = $this->game->playDisc( $x, $y );
self::ajaxResponse( );
}
</pre>

As you can see, we get the 2 arguments x and y from the javascript call, and call a corresponding "playDisc" method in our game logic.

Now, let's have a look of this playDisc method:

<pre>
function playDisc( $x, $y )
{
// Check that this player is active and that this action is possible at this moment
self::checkAction( 'playDisc' );
</pre>

... at first, we check that this action is possible according to current game state (see "possible action"). We already did it on client side, but it's important to do it on server side too (otherwise it would be possible to cheat).

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

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

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

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

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

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

self::DbQuery( $sql );

</pre>

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

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

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

</pre>

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

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

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

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

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

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

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

A last thing to do on the server side is to active the next player when we enter in the "nextPlayer" game state:

<pre>
function stNextPlayer()
{
// Active next player
$player_id = self::activeNextPlayer();

self::giveExtraTime( $player_id );
$this->gamestate->nextState( 'nextTurn' );

}
</pre>

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

[[File:reversi9.jpg]]

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

== Make the move appears automatically ==

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

In our "setupNotifications" method, we register 2 methods for the 2 notifications we created at the previous step ('playDisc' and 'turnOverDiscs'):

<pre>
dojo.subscribe( 'playDisc', this, "notif_playDisc" );
this.notifqueue.setSynchronous( 'playDisc', 500 );
dojo.subscribe( 'turnOverDiscs', this, "notif_turnOverDiscs" );
this.notifqueue.setSynchronous( 'turnOverDiscs', 1500 );
</pre>

As you can see, we associate our 2 notifications with 2 methods with the "notif_" prefix. At the same time, we define these notifications as "synchronous", with a duration in millisecond (500 for the first one, and 1500 for the second one). It tells the user interface to wait some time after executing the notification, to let the animation end before starting the next notification. In our specific case, the animation will be the following:
* Make a disc slide from the player panel to its place on the board
* (wait 500ms)
* Make all turned over discs blink (and of course turned them over)
* (wait 1500ms)
* Let the next player play.

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

<pre>
notif_playDisc: function( notif )
{
// Remove current possible moves (makes the board more clear)
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );

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

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

Now, here's the method that handle the turnOverDiscs notification:

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

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

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

// Remove any color class
dojo.removeClass( node, [ 'disccolor_000000', 'disccolor_ffffff' ] );
// ... and add the good one
dojo.addClass( node, 'disccolor_'+targetColor );

}
} ),
dojo.fadeIn( { node: 'disc_'+disc.x+''+disc.y } )

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

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

The list of the discs 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 it. The complete documentation on dojo animations [http://dojotoolkit.org/documentation/tutorials/1.6/animation/ can be found here].

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

Tutorial reversi

2012-12-06T00:36:07Z

Pikiou: /* Setup the initial game position */ Typos

== Introduction ==

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

Before you read this tutorial, you must:
* Read the overall presentations of the BGA Framework ([[Studio|see here]]).
* Know the [http://en.wikipedia.org/wiki/Reversi#Rules rules of Reversi].
* Know the languages used on BGA: PHP, SQL, HTML, CSS, Javascript.

== Create your first game ==

With the initial skeleton of code provided initially, you can already start a game from the BGA Studio. For now, we are going to work with 1 player only. Most of the time 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.

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

== Let it look like Reversi ==

It's always a good idea to start with a little bit of graphic work. Why? Because this helps to figure out how the final game will be, and issues that may appear later.

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

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

[[File:Board.jpg]]

Note that we are using a jpg file. Jpg are lighter than png, so faster to load. Later we are going to use PNGs for discs for transparency purpose.

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

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

* edit your reversi.css file to transform it into a visible board:

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

Refresh your page. Here's your board:

[[File:reversi1.jpg]]

== Make the squares appears ==

Now, what we need is to create some invisible HTML elements where squares are. These elements will be used as position references for width and black discs.
Obviously, we need 64 squares. To avoid writing 64 'div' elements on our template, we are going to use the "block" feature.

Let's modify our template like this:

<pre>
<div id="board">

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

</div>
</pre>

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.

Let's do it in our "reversi.view.php" file:

<pre>
$this->page->begin_block( "reversi_reversi", "square" );

$hor_scale = 64.8;
$ver_scale = 64.4;
for( $x=1; $x<=8; $x++ )
{
for( $y=1; $y<=8; $y++ )
{
$this->page->insert_block( "square", array(
'X' => $x,
'Y' => $y,
'LEFT' => round( ($x-1)*$hor_scale+10 ),
'TOP' => round( ($y-1)*$ver_scale+7 )
) );
}
}
</pre>

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.

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

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

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

Explanations:
* With "position: relative" on board, we ensure square elements are positioned relatively to board.
* For the test, we use a red background color for the square. This is a useful tip to figure out if everything is fine with invisible elements.

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

[[File:reversi2.jpg]]

== The discs ==

Now, our board is ready to receive some disc tokens!

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

<pre>


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

Then, let's introduce a new piece of art with the discs. We need some transparency here so we are using a png file:

[[File:tokens.png]]

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].

Now, let's separate the disc with some CSS stuff:

<pre>
.token {
width: 56px;
height: 56px;
position: absolute;
background-image: url('../../img/reversi/tokens.png');
}
.tokencolor_ffffff { background-position: 0px 0px; }
.tokencolor_000000 { background-position: -56px 0px; }
</pre>

With this CSS code, we apply the classes "token" and "tokencolor_ffffff" to a div element and we've got a white token. Yeah.

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

Now, let's make a first token appear on our board. Disc tokens are not visible at the beginning of the game: they appear dynamically during the game. For this reason, we are going to make them appear from our Javascript code, with a BGA Framework technique called "JS template".

In our template file (reversi_reversi.tpl), let's create the piece of HTML needed to display our token:

<pre>
<script type="text/javascript">

// Templates

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

</script>
</pre>

Note: we already created the "templates" section for you in the game skeleton.

As you can see, we defined a JS template named "jstpl_token" with a piece of HTML and two variables: the color of the token and its x/y coordinates. Note that the syntax of the argument is different for template block variables (brackets) and JS template variables (dollar and brackets).

Now, let's create a method in our Javascript code that will make a token appear on the board, using this template:

<pre>
addTokenOnBoard: function( x, y, player )
{
dojo.place( this.format_block( 'jstpl_token', {
x_y: x+'_'+y,
color: this.gamedatas.players[ player ].color
} ) , 'tokens' );

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

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.

Then, with BGA "this.placeOnObject" method, we place this element over the panel of some player. Immediately after, using BGA "this.slidetoObject" method, we make the disc slide to the "square" element, its final destination.

Note: don't forget to call the "play()", otherwise the token remains at its original location.

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.

Now, to test if everything works fine, just call "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:

[[File:reversi3.jpg]]

== The database ==

We did most of the client-side programming, so let's have a look on the other side now.

To design the database model of our game, 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.

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.

[[File:reversi4.jpg]]

The database model of Reversi is very simple: just one table with the squares of the board. In our dbmodel.sql, we have this:

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

Now, a new database with a "board" table will be created each time we start a Reversi game. This is why after modifying our dbmodel.sql it's a good time to stop & start again our game.

== Setup the initial game position ==

The "setupNewGame" method of our reversi.game.php is called during initial setup: this is the place to initialize our data and to place the initial tokens on the board (initially, there are 4 tokens on the board).

Let's do this:

<pre>
// Init the board
$sql = "INSERT INTO board (board_x,board_y,board_player) VALUES ";
$sql_values = array();
for( $x=1; $x<=8; $x++ )
{
for( $y=1; $y<=8; $y++ )
{
$token_value = "NULL";
if( ($x==4 && $y==4) || ($x==5 && $y==5) ) // Initial positions of white player
$token_value = "'$whiteplayer_id'";
else if( ($x==4 && $y==5) || ($x==5 && $y==4) ) // Initial positions of black player
$token_value = "'$blackplayer_id'";

$sql_values[] = "('$x','$y',$token_value)";
}
}
$sql .= implode( $sql_values, ',' );
self::DbQuery( $sql );

// Active first player
self::activeNextPlayer();
</pre>

As you can see, we create one table entry for each square, with a "NULL" value which means "empty square". Of course, for 4 specific squares, we place an initial token.

At the end, we call activeNextPlayer to make the first player active at the beginning of the game.

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

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

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.

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:

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

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

As you can see, our "board" entry created in "getAllDatas" can be used here as "gamedatas.board" in our Javascript. We are using our previously developed "addTokenOnBoard" method.

Reload... and here we are:

[[File:reversi5.jpg]]

It starts to smell Reversi here...

== The game state machine ==

Now, let's stop our game again, because we are going to start the core game logic.

You already read the "Focus on BGA game state machine", so you know that this is the heart of your game logic. For reversi game, it's very simple although. Here's a diagram of our game state machine for Reversi:

[[File:reversi6.jpg]]

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

<pre>
$machinestates = array(

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

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

11 => array(
"name" => "nextPlayer",
"type" => "game",
"action" => "stNextPlayer",
"updateGameProgression" => true,
"transitions" => array( "nextTurn" => 10, "cantPlay" => 11, "endGame" => 99 )
),

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

);
</pre>

Now, let's create in our reversi.game.php file the methods that are declared in this game states description file:
* argPlayerTurn
* stNextPlayer

... and start a new Reversi game.

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

[[File:reversi7.jpg]]

== The rules ==

Now, what we would like to do is to indicate to the current player where it is allowed to play. The idea is to build a "getPossibleMoves" PHP method that return a list of coordinates where it is allowed to play. This method will be used in particular:
* As we just said, to help the player to see where he can play.
* When the player play, to check if he has the right to play here.

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

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.

If you want to look into details, please look at the "utility method" sections of reversi.game.php.

== Display allowed moves ==

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

To do this, we are using the "argPlayerTurn" method. This method is called each time we enter into "playerTurn" game state, and its result is transfered automatically to the client-side:

<pre>

function argPlayerTurn()
{
return array(
'possibleMoves' => self::getPossibleMoves( self::getActivePlayerId() )
);
}
</pre>

We are of course using the "getPossibleMoves" method we just developed.

Now, let's go to the client side to use the data returned by the method above. We are using the "onEnteringState" Javascript method that is called each time we enter into a new game state:

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

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

So, when we are entering into "playerTurn" game state, we are calling our "updatePossibleMoves" method. This method looks like this:

<pre>
updatePossibleMoves: function( possibleMoves )
{
// Remove current possible moves
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );

for( var x in possibleMoves )
{
for( var y in possibleMoves[ x ] )
{
// x,y is a possible move
dojo.addClass( 'square_'+x+'_'+y, 'possibleMove' );
}
}

this.addTooltipToClass( 'possibleMove', '', _('Place a disc here') );
},
</pre>

The idea here is that we've created a CSS class ("possibleMove") that can be applied to a "square" element to highlight it.

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

Then we loop through all possible moves that our PHP "updatePossibleMoves" create for us, and add the "possibleMove" class to corresponding square.

Finally, we use BGA framework "addTooltipToClass" method to associate a tooltip to all these highlighted squares in order players can understand the meaning of this.

And here we are:

[[File:reversi8.jpg.jpg]]

== Let's play ==

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

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

<pre>
dojo.query( '.square' ).connect( 'onclick', this, 'onPlayDisc' );
</pre>

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

Here's our "onPlayDisc" method below:

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

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

if( ! dojo.hasClass( 'square_'+x+'_'+y, 'possibleMove' ) )
{
// This is not a possible move => the click does nothing
return ;
}

if( this.checkAction( 'playDisc' ) ) // Check that this action is possible at this moment
{
this.ajaxcall( "/reversi/reversi/playDisc.html", {
x:x,
y:y
}, this, function( result ) {} );
}
},
</pre>

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

Now, we have to manage this "playDisc" action on server side. At first, we introduce a "playDisc" entry point in our "reversi.action.php":

<pre>
public function playDisc()
{
self::setAjaxMode();
$x = self::getArg( "x", AT_posint, true );
$y = self::getArg( "y", AT_posint, true );
$result = $this->game->playDisc( $x, $y );
self::ajaxResponse( );
}
</pre>

As you can see, we get the 2 arguments x and y from the javascript call, and call a corresponding "playDisc" method in our game logic.

Now, let's have a look of this playDisc method:

<pre>
function playDisc( $x, $y )
{
// Check that this player is active and that this action is possible at this moment
self::checkAction( 'playDisc' );
</pre>

... at first, we check that this action is possible according to current game state (see "possible action"). We already did it on client side, but it's important to do it on server side too (otherwise it would be possible to cheat).

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

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

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

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

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

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

self::DbQuery( $sql );

</pre>

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

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

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

</pre>

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

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

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

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

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

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

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

A last thing to do on the server side is to active the next player when we enter in the "nextPlayer" game state:

<pre>
function stNextPlayer()
{
// Active next player
$player_id = self::activeNextPlayer();

self::giveExtraTime( $player_id );
$this->gamestate->nextState( 'nextTurn' );

}
</pre>

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

[[File:reversi9.jpg]]

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

== Make the move appears automatically ==

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

In our "setupNotifications" method, we register 2 methods for the 2 notifications we created at the previous step ('playDisc' and 'turnOverDiscs'):

<pre>
dojo.subscribe( 'playDisc', this, "notif_playDisc" );
this.notifqueue.setSynchronous( 'playDisc', 500 );
dojo.subscribe( 'turnOverDiscs', this, "notif_turnOverDiscs" );
this.notifqueue.setSynchronous( 'turnOverDiscs', 1500 );
</pre>

As you can see, we associate our 2 notifications with 2 methods with the "notif_" prefix. At the same time, we define these notifications as "synchronous", with a duration in millisecond (500 for the first one, and 1500 for the second one). It tells the user interface to wait some time after executing the notification, to let the animation end before starting the next notification. In our specific case, the animation will be the following:
* Make a disc slide from the player panel to its place on the board
* (wait 500ms)
* Make all turned over discs blink (and of course turned them over)
* (wait 1500ms)
* Let the next player play.

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

<pre>
notif_playDisc: function( notif )
{
// Remove current possible moves (makes the board more clear)
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );

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

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

Now, here's the method that handle the turnOverDiscs notification:

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

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

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

// Remove any color class
dojo.removeClass( node, [ 'disccolor_000000', 'disccolor_ffffff' ] );
// ... and add the good one
dojo.addClass( node, 'disccolor_'+targetColor );

}
} ),
dojo.fadeIn( { node: 'disc_'+disc.x+''+disc.y } )

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

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

The list of the discs 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 it. The complete documentation on dojo animations [http://dojotoolkit.org/documentation/tutorials/1.6/animation/ can be found here].

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

Tutorial reversi

2012-12-05T23:11:55Z

Pikiou: Buggy code because of a missing underscore between x and y

== Introduction ==

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

Before you read this tutorial, you must:
* Read the overall presentations of the BGA Framework ([[Studio|see here]]).
* Know the [http://en.wikipedia.org/wiki/Reversi#Rules rules of Reversi].
* Know the languages used on BGA: PHP, SQL, HTML, CSS, Javascript.

== Create your first game ==

With the initial skeleton of code provided initially, you can already start a game from the BGA Studio. For now, we are going to work with 1 player only. Most of the time 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.

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

== Let it look like Reversi ==

It's always a good idea to start with a little bit of graphic work. Why? Because this helps to figure out how the final game will be, and issues that may appear later.

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

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

[[File:Board.jpg]]

Note that we are using a jpg file. Jpg are lighter than png, so faster to load. Later we are going to use PNGs for discs for transparency purpose.

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

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

* edit your reversi.css file to transform it into a visible board:

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

Refresh your page. Here's your board:

[[File:reversi1.jpg]]

== Make the squares appears ==

Now, what we need is to create some invisible HTML elements where squares are. These elements will be used as position references for width and black discs.
Obviously, we need 64 squares. To avoid writing 64 'div' elements on our template, we are going to use the "block" feature.

Let's modify our template like this:

<pre>
<div id="board">

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

</div>
</pre>

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.

Let's do it in our "reversi.view.php" file:

<pre>
$this->page->begin_block( "reversi_reversi", "square" );

$hor_scale = 64.8;
$ver_scale = 64.4;
for( $x=1; $x<=8; $x++ )
{
for( $y=1; $y<=8; $y++ )
{
$this->page->insert_block( "square", array(
'X' => $x,
'Y' => $y,
'LEFT' => round( ($x-1)*$hor_scale+10 ),
'TOP' => round( ($y-1)*$ver_scale+7 )
) );
}
}
</pre>

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.

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

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

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

Explanations:
* With "position: relative" on board, we ensure square elements are positioned relatively to board.
* For the test, we use a red background color for the square. This is a useful tip to figure out if everything is fine with invisible elements.

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

[[File:reversi2.jpg]]

== The discs ==

Now, our board is ready to receive some disc tokens!

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

<pre>


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

Then, let's introduce a new piece of art with the discs. We need some transparency here so we are using a png file:

[[File:tokens.png]]

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].

Now, let's separate the disc with some CSS stuff:

<pre>
.token {
width: 56px;
height: 56px;
position: absolute;
background-image: url('../../img/reversi/tokens.png');
}
.tokencolor_ffffff { background-position: 0px 0px; }
.tokencolor_000000 { background-position: -56px 0px; }
</pre>

With this CSS code, we apply the classes "token" and "tokencolor_ffffff" to a div element and we've got a white token. Yeah.

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

Now, let's make a first token appear on our board. Disc tokens are not visible at the beginning of the game: they appear dynamically during the game. For this reason, we are going to make them appear from our Javascript code, with a BGA Framework technique called "JS template".

In our template file (reversi_reversi.tpl), let's create the piece of HTML needed to display our token:

<pre>
<script type="text/javascript">

// Templates

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

</script>
</pre>

Note: we already created the "templates" section for you in the game skeleton.

As you can see, we defined a JS template named "jstpl_token" with a piece of HTML and two variables: the color of the token and its x/y coordinates. Note that the syntax of the argument is different for template block variables (brackets) and JS template variables (dollar and brackets).

Now, let's create a method in our Javascript code that will make a token appear on the board, using this template:

<pre>
addTokenOnBoard: function( x, y, player )
{
dojo.place( this.format_block( 'jstpl_token', {
x_y: x+'_'+y,
color: this.gamedatas.players[ player ].color
} ) , 'tokens' );

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

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.

Then, with BGA "this.placeOnObject" method, we place this element over the panel of some player. Immediately after, using BGA "this.slidetoObject" method, we make the disc slide to the "square" element, its final destination.

Note: don't forget to call the "play()", otherwise the token remains at its original location.

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.

Now, to test if everything works fine, just call "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:

[[File:reversi3.jpg]]

== The database ==

We did most of the client-side programming, so let's have a look on the other side now.

To design the database model of our game, 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.

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.

[[File:reversi4.jpg]]

The database model of Reversi is very simple: just one table with the squares of the board. In our dbmodel.sql, we have this:

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

Now, a new database with a "board" table will be created each time we start a Reversi game. This is why after modifying our dbmodel.sql it's a good time to stop & start again our game.

== Setup the initial game position ==

The "setupNewGame" method of our reversi.game.php is called during initial setup: this is the place to initialize our data and to place the initial tokens on the board (initially, there are 4 tokens on the board).

Let's do this:

<pre>
// Init the board
$sql = "INSERT INTO board (board_x,board_y,board_player) VALUES ";
$sql_values = array();
for( $x=1; $x<=8; $x++ )
{
for( $y=1; $y<=8; $y++ )
{
$token_value = "NULL";
if( ($x==4 && $y==4) || ($x==5 && $y==5) ) // Initial positions of white player
$token_value = "'$whiteplayer_id'";
else if( ($x==4 && $y==5) || ($x==5 && $y==4) ) // Initial positions of black player
$token_value = "'$blackplayer_id'";

$sql_values[] = "('$x','$y',$token_value)";
}
}
$sql .= implode( $sql_values, ',' );
self::DbQuery( $sql );

// Active first player
self::activeNextPlayer();
</pre>

As you can see, we create one database entry for each square, with a "NULL" value which mean "empty square". Of course, for 4 specific squares, we place an initial token.

At the end, we active the first player to make it active at the beginning of the game.

Now, we need to make these tokens appears 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):

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

As you can see, we are using the BGA framework "getObjectListFromDB" method that format the result of this SQL query in a PHP array with x, y and player attribute.

The last thing we need to do is to process this array on 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:

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

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

As you can see, our "board" entry created in "getAllDatas" can be used here as "gamedatas.board" in our Javascript. We are using our previously developed "addTokenOnBoard" method.

Reload... and here we are:

[[File:reversi5.jpg]]

It starts to smell Reversi here...

== The game state machine ==

Now, let's stop our game again, because we are going to start the core game logic.

You already read the "Focus on BGA game state machine", so you know that this is the heart of your game logic. For reversi game, it's very simple although. Here's a diagram of our game state machine for Reversi:

[[File:reversi6.jpg]]

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

<pre>
$machinestates = array(

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

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

11 => array(
"name" => "nextPlayer",
"type" => "game",
"action" => "stNextPlayer",
"updateGameProgression" => true,
"transitions" => array( "nextTurn" => 10, "cantPlay" => 11, "endGame" => 99 )
),

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

);
</pre>

Now, let's create in our reversi.game.php file the methods that are declared in this game states description file:
* argPlayerTurn
* stNextPlayer

... and start a new Reversi game.

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

[[File:reversi7.jpg]]

== The rules ==

Now, what we would like to do is to indicate to the current player where it is allowed to play. The idea is to build a "getPossibleMoves" PHP method that return a list of coordinates where it is allowed to play. This method will be used in particular:
* As we just said, to help the player to see where he can play.
* When the player play, to check if he has the right to play here.

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

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.

If you want to look into details, please look at the "utility method" sections of reversi.game.php.

== Display allowed moves ==

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

To do this, we are using the "argPlayerTurn" method. This method is called each time we enter into "playerTurn" game state, and its result is transfered automatically to the client-side:

<pre>

function argPlayerTurn()
{
return array(
'possibleMoves' => self::getPossibleMoves( self::getActivePlayerId() )
);
}
</pre>

We are of course using the "getPossibleMoves" method we just developed.

Now, let's go to the client side to use the data returned by the method above. We are using the "onEnteringState" Javascript method that is called each time we enter into a new game state:

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

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

So, when we are entering into "playerTurn" game state, we are calling our "updatePossibleMoves" method. This method looks like this:

<pre>
updatePossibleMoves: function( possibleMoves )
{
// Remove current possible moves
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );

for( var x in possibleMoves )
{
for( var y in possibleMoves[ x ] )
{
// x,y is a possible move
dojo.addClass( 'square_'+x+'_'+y, 'possibleMove' );
}
}

this.addTooltipToClass( 'possibleMove', '', _('Place a disc here') );
},
</pre>

The idea here is that we've created a CSS class ("possibleMove") that can be applied to a "square" element to highlight it.

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

Then we loop through all possible moves that our PHP "updatePossibleMoves" create for us, and add the "possibleMove" class to corresponding square.

Finally, we use BGA framework "addTooltipToClass" method to associate a tooltip to all these highlighted squares in order players can understand the meaning of this.

And here we are:

[[File:reversi8.jpg.jpg]]

== Let's play ==

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

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

<pre>
dojo.query( '.square' ).connect( 'onclick', this, 'onPlayDisc' );
</pre>

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

Here's our "onPlayDisc" method below:

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

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

if( ! dojo.hasClass( 'square_'+x+'_'+y, 'possibleMove' ) )
{
// This is not a possible move => the click does nothing
return ;
}

if( this.checkAction( 'playDisc' ) ) // Check that this action is possible at this moment
{
this.ajaxcall( "/reversi/reversi/playDisc.html", {
x:x,
y:y
}, this, function( result ) {} );
}
},
</pre>

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

Now, we have to manage this "playDisc" action on server side. At first, we introduce a "playDisc" entry point in our "reversi.action.php":

<pre>
public function playDisc()
{
self::setAjaxMode();
$x = self::getArg( "x", AT_posint, true );
$y = self::getArg( "y", AT_posint, true );
$result = $this->game->playDisc( $x, $y );
self::ajaxResponse( );
}
</pre>

As you can see, we get the 2 arguments x and y from the javascript call, and call a corresponding "playDisc" method in our game logic.

Now, let's have a look of this playDisc method:

<pre>
function playDisc( $x, $y )
{
// Check that this player is active and that this action is possible at this moment
self::checkAction( 'playDisc' );
</pre>

... at first, we check that this action is possible according to current game state (see "possible action"). We already did it on client side, but it's important to do it on server side too (otherwise it would be possible to cheat).

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

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

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

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

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

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

self::DbQuery( $sql );

</pre>

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

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

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

</pre>

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

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

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

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

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

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

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

A last thing to do on the server side is to active the next player when we enter in the "nextPlayer" game state:

<pre>
function stNextPlayer()
{
// Active next player
$player_id = self::activeNextPlayer();

self::giveExtraTime( $player_id );
$this->gamestate->nextState( 'nextTurn' );

}
</pre>

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

[[File:reversi9.jpg]]

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

== Make the move appears automatically ==

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

In our "setupNotifications" method, we register 2 methods for the 2 notifications we created at the previous step ('playDisc' and 'turnOverDiscs'):

<pre>
dojo.subscribe( 'playDisc', this, "notif_playDisc" );
this.notifqueue.setSynchronous( 'playDisc', 500 );
dojo.subscribe( 'turnOverDiscs', this, "notif_turnOverDiscs" );
this.notifqueue.setSynchronous( 'turnOverDiscs', 1500 );
</pre>

As you can see, we associate our 2 notifications with 2 methods with the "notif_" prefix. At the same time, we define these notifications as "synchronous", with a duration in millisecond (500 for the first one, and 1500 for the second one). It tells the user interface to wait some time after executing the notification, to let the animation end before starting the next notification. In our specific case, the animation will be the following:
* Make a disc slide from the player panel to its place on the board
* (wait 500ms)
* Make all turned over discs blink (and of course turned them over)
* (wait 1500ms)
* Let the next player play.

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

<pre>
notif_playDisc: function( notif )
{
// Remove current possible moves (makes the board more clear)
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );

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

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

Now, here's the method that handle the turnOverDiscs notification:

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

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

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

// Remove any color class
dojo.removeClass( node, [ 'disccolor_000000', 'disccolor_ffffff' ] );
// ... and add the good one
dojo.addClass( node, 'disccolor_'+targetColor );

}
} ),
dojo.fadeIn( { node: 'disc_'+disc.x+''+disc.y } )

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

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

The list of the discs 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 it. The complete documentation on dojo animations [http://dojotoolkit.org/documentation/tutorials/1.6/animation/ can be found here].

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

Tutorial reversi

2012-12-05T23:10:00Z

Pikiou: Buggy code result of mixing the words disc and token

== Introduction ==

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

Before you read this tutorial, you must:
* Read the overall presentations of the BGA Framework ([[Studio|see here]]).
* Know the [http://en.wikipedia.org/wiki/Reversi#Rules rules of Reversi].
* Know the languages used on BGA: PHP, SQL, HTML, CSS, Javascript.

== Create your first game ==

With the initial skeleton of code provided initially, you can already start a game from the BGA Studio. For now, we are going to work with 1 player only. Most of the time 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.

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

== Let it look like Reversi ==

It's always a good idea to start with a little bit of graphic work. Why? Because this helps to figure out how the final game will be, and issues that may appear later.

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

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

[[File:Board.jpg]]

Note that we are using a jpg file. Jpg are lighter than png, so faster to load. Later we are going to use PNGs for discs for transparency purpose.

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

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

* edit your reversi.css file to transform it into a visible board:

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

Refresh your page. Here's your board:

[[File:reversi1.jpg]]

== Make the squares appears ==

Now, what we need is to create some invisible HTML elements where squares are. These elements will be used as position references for width and black discs.
Obviously, we need 64 squares. To avoid writing 64 'div' elements on our template, we are going to use the "block" feature.

Let's modify our template like this:

<pre>
<div id="board">

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

</div>
</pre>

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.

Let's do it in our "reversi.view.php" file:

<pre>
$this->page->begin_block( "reversi_reversi", "square" );

$hor_scale = 64.8;
$ver_scale = 64.4;
for( $x=1; $x<=8; $x++ )
{
for( $y=1; $y<=8; $y++ )
{
$this->page->insert_block( "square", array(
'X' => $x,
'Y' => $y,
'LEFT' => round( ($x-1)*$hor_scale+10 ),
'TOP' => round( ($y-1)*$ver_scale+7 )
) );
}
}
</pre>

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.

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

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

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

Explanations:
* With "position: relative" on board, we ensure square elements are positioned relatively to board.
* For the test, we use a red background color for the square. This is a useful tip to figure out if everything is fine with invisible elements.

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

[[File:reversi2.jpg]]

== The discs ==

Now, our board is ready to receive some disc tokens!

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

<pre>


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

Then, let's introduce a new piece of art with the discs. We need some transparency here so we are using a png file:

[[File:tokens.png]]

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].

Now, let's separate the disc with some CSS stuff:

<pre>
.token {
width: 56px;
height: 56px;
position: absolute;
background-image: url('../../img/reversi/tokens.png');
}
.tokencolor_ffffff { background-position: 0px 0px; }
.tokencolor_000000 { background-position: -56px 0px; }
</pre>

With this CSS code, we apply the classes "token" and "tokencolor_ffffff" to a div element and we've got a white token. Yeah.

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

Now, let's make a first token appear on our board. Disc tokens are not visible at the beginning of the game: they appear dynamically during the game. For this reason, we are going to make them appear from our Javascript code, with a BGA Framework technique called "JS template".

In our template file (reversi_reversi.tpl), let's create the piece of HTML needed to display our token:

<pre>
<script type="text/javascript">

// Templates

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

</script>
</pre>

Note: we already created the "templates" section for you in the game skeleton.

As you can see, we defined a JS template named "jstpl_token" with a piece of HTML and two variables: the color of the token and its x/y coordinates. Note that the syntax of the argument is different for template block variables (brackets) and JS template variables (dollar and brackets).

Now, let's create a method in our Javascript code that will make a token appear on the board, using this template:

<pre>
addTokenOnBoard: function( x, y, player )
{
dojo.place( this.format_block( 'jstpl_token', {
xy: x+''+y,
color: this.gamedatas.players[ player ].color
} ) , 'tokens' );

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

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.

Then, with BGA "this.placeOnObject" method, we place this element over the panel of some player. Immediately after, using BGA "this.slidetoObject" method, we make the disc slide to the "square" element, its final destination.

Note: don't forget to call the "play()", otherwise the token remains at its original location.

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.

Now, to test if everything works fine, just call "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:

[[File:reversi3.jpg]]

== The database ==

We did most of the client-side programming, so let's have a look on the other side now.

To design the database model of our game, 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.

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.

[[File:reversi4.jpg]]

The database model of Reversi is very simple: just one table with the squares of the board. In our dbmodel.sql, we have this:

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

Now, a new database with a "board" table will be created each time we start a Reversi game. This is why after modifying our dbmodel.sql it's a good time to stop & start again our game.

== Setup the initial game position ==

The "setupNewGame" method of our reversi.game.php is called during initial setup: this is the place to initialize our data and to place the initial tokens on the board (initially, there are 4 tokens on the board).

Let's do this:

<pre>
// Init the board
$sql = "INSERT INTO board (board_x,board_y,board_player) VALUES ";
$sql_values = array();
for( $x=1; $x<=8; $x++ )
{
for( $y=1; $y<=8; $y++ )
{
$token_value = "NULL";
if( ($x==4 && $y==4) || ($x==5 && $y==5) ) // Initial positions of white player
$token_value = "'$whiteplayer_id'";
else if( ($x==4 && $y==5) || ($x==5 && $y==4) ) // Initial positions of black player
$token_value = "'$blackplayer_id'";

$sql_values[] = "('$x','$y',$token_value)";
}
}
$sql .= implode( $sql_values, ',' );
self::DbQuery( $sql );

// Active first player
self::activeNextPlayer();
</pre>

As you can see, we create one database entry for each square, with a "NULL" value which mean "empty square". Of course, for 4 specific squares, we place an initial token.

At the end, we active the first player to make it active at the beginning of the game.

Now, we need to make these tokens appears 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):

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

As you can see, we are using the BGA framework "getObjectListFromDB" method that format the result of this SQL query in a PHP array with x, y and player attribute.

The last thing we need to do is to process this array on 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:

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

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

As you can see, our "board" entry created in "getAllDatas" can be used here as "gamedatas.board" in our Javascript. We are using our previously developed "addTokenOnBoard" method.

Reload... and here we are:

[[File:reversi5.jpg]]

It starts to smell Reversi here...

== The game state machine ==

Now, let's stop our game again, because we are going to start the core game logic.

You already read the "Focus on BGA game state machine", so you know that this is the heart of your game logic. For reversi game, it's very simple although. Here's a diagram of our game state machine for Reversi:

[[File:reversi6.jpg]]

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

<pre>
$machinestates = array(

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

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

11 => array(
"name" => "nextPlayer",
"type" => "game",
"action" => "stNextPlayer",
"updateGameProgression" => true,
"transitions" => array( "nextTurn" => 10, "cantPlay" => 11, "endGame" => 99 )
),

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

);
</pre>

Now, let's create in our reversi.game.php file the methods that are declared in this game states description file:
* argPlayerTurn
* stNextPlayer

... and start a new Reversi game.

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

[[File:reversi7.jpg]]

== The rules ==

Now, what we would like to do is to indicate to the current player where it is allowed to play. The idea is to build a "getPossibleMoves" PHP method that return a list of coordinates where it is allowed to play. This method will be used in particular:
* As we just said, to help the player to see where he can play.
* When the player play, to check if he has the right to play here.

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

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.

If you want to look into details, please look at the "utility method" sections of reversi.game.php.

== Display allowed moves ==

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

To do this, we are using the "argPlayerTurn" method. This method is called each time we enter into "playerTurn" game state, and its result is transfered automatically to the client-side:

<pre>

function argPlayerTurn()
{
return array(
'possibleMoves' => self::getPossibleMoves( self::getActivePlayerId() )
);
}
</pre>

We are of course using the "getPossibleMoves" method we just developed.

Now, let's go to the client side to use the data returned by the method above. We are using the "onEnteringState" Javascript method that is called each time we enter into a new game state:

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

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

So, when we are entering into "playerTurn" game state, we are calling our "updatePossibleMoves" method. This method looks like this:

<pre>
updatePossibleMoves: function( possibleMoves )
{
// Remove current possible moves
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );

for( var x in possibleMoves )
{
for( var y in possibleMoves[ x ] )
{
// x,y is a possible move
dojo.addClass( 'square_'+x+'_'+y, 'possibleMove' );
}
}

this.addTooltipToClass( 'possibleMove', '', _('Place a disc here') );
},
</pre>

The idea here is that we've created a CSS class ("possibleMove") that can be applied to a "square" element to highlight it.

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

Then we loop through all possible moves that our PHP "updatePossibleMoves" create for us, and add the "possibleMove" class to corresponding square.

Finally, we use BGA framework "addTooltipToClass" method to associate a tooltip to all these highlighted squares in order players can understand the meaning of this.

And here we are:

[[File:reversi8.jpg.jpg]]

== Let's play ==

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

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

<pre>
dojo.query( '.square' ).connect( 'onclick', this, 'onPlayDisc' );
</pre>

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

Here's our "onPlayDisc" method below:

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

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

if( ! dojo.hasClass( 'square_'+x+'_'+y, 'possibleMove' ) )
{
// This is not a possible move => the click does nothing
return ;
}

if( this.checkAction( 'playDisc' ) ) // Check that this action is possible at this moment
{
this.ajaxcall( "/reversi/reversi/playDisc.html", {
x:x,
y:y
}, this, function( result ) {} );
}
},
</pre>

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

Now, we have to manage this "playDisc" action on server side. At first, we introduce a "playDisc" entry point in our "reversi.action.php":

<pre>
public function playDisc()
{
self::setAjaxMode();
$x = self::getArg( "x", AT_posint, true );
$y = self::getArg( "y", AT_posint, true );
$result = $this->game->playDisc( $x, $y );
self::ajaxResponse( );
}
</pre>

As you can see, we get the 2 arguments x and y from the javascript call, and call a corresponding "playDisc" method in our game logic.

Now, let's have a look of this playDisc method:

<pre>
function playDisc( $x, $y )
{
// Check that this player is active and that this action is possible at this moment
self::checkAction( 'playDisc' );
</pre>

... at first, we check that this action is possible according to current game state (see "possible action"). We already did it on client side, but it's important to do it on server side too (otherwise it would be possible to cheat).

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

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

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

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

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

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

self::DbQuery( $sql );

</pre>

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

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

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

</pre>

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

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

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

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

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

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

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

A last thing to do on the server side is to active the next player when we enter in the "nextPlayer" game state:

<pre>
function stNextPlayer()
{
// Active next player
$player_id = self::activeNextPlayer();

self::giveExtraTime( $player_id );
$this->gamestate->nextState( 'nextTurn' );

}
</pre>

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

[[File:reversi9.jpg]]

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

== Make the move appears automatically ==

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

In our "setupNotifications" method, we register 2 methods for the 2 notifications we created at the previous step ('playDisc' and 'turnOverDiscs'):

<pre>
dojo.subscribe( 'playDisc', this, "notif_playDisc" );
this.notifqueue.setSynchronous( 'playDisc', 500 );
dojo.subscribe( 'turnOverDiscs', this, "notif_turnOverDiscs" );
this.notifqueue.setSynchronous( 'turnOverDiscs', 1500 );
</pre>

As you can see, we associate our 2 notifications with 2 methods with the "notif_" prefix. At the same time, we define these notifications as "synchronous", with a duration in millisecond (500 for the first one, and 1500 for the second one). It tells the user interface to wait some time after executing the notification, to let the animation end before starting the next notification. In our specific case, the animation will be the following:
* Make a disc slide from the player panel to its place on the board
* (wait 500ms)
* Make all turned over discs blink (and of course turned them over)
* (wait 1500ms)
* Let the next player play.

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

<pre>
notif_playDisc: function( notif )
{
// Remove current possible moves (makes the board more clear)
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );

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

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

Now, here's the method that handle the turnOverDiscs notification:

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

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

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

// Remove any color class
dojo.removeClass( node, [ 'disccolor_000000', 'disccolor_ffffff' ] );
// ... and add the good one
dojo.addClass( node, 'disccolor_'+targetColor );

}
} ),
dojo.fadeIn( { node: 'disc_'+disc.x+''+disc.y } )

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

// ... and launch the animation
anim.play();
}
},
</pre>

The list of the discs 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 it. The complete documentation on dojo animations [http://dojotoolkit.org/documentation/tutorials/1.6/animation/ can be found here].

In few words: we create a chain of 4 animations to make the disc fade out, fade in, fade out again, and fade in again. At the end of the second fade out, we change the color of the disc. Finally, we launch the animation with "play()".

Tutorial reversi

2012-12-05T23:05:05Z

Pikiou: Typos

== Introduction ==

Using this tutorial, you can build a complete working game on the BGA environment: Reversi.

Before you read this tutorial, you must:
* Read the overall presentations of the BGA Framework ([[Studio|see here]]).
* Know the [http://en.wikipedia.org/wiki/Reversi#Rules rules of Reversi].
* Know the languages used on BGA: PHP, SQL, HTML, CSS, Javascript.

== Create your first game ==

With the initial skeleton of code provided initially, you can already start a game from the BGA Studio. For now, we are going to work with 1 player only. Most of the time 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.

Thus, you can start a "Reversi" game, and arrive on a void, empty game. Yeah.

== Let it look like Reversi ==

It's always a good idea to start with a little bit of graphic work. Why? Because this helps to figure out how the final game will be, and issues that may appear later.

Be careful designing the layout of your game: you must always keep in mind that players with a 1024px screen width must be able to play. Usually, it means that the width of the play area can be 750px (in the worst case).

For Reversi, it's useless to have a 750x750px board - much too big, so we choose this one which fit perfectly (536x528):

[[File:Board.jpg]]

Note that we are using a jpg file. Jpg are lighter than png, so faster to load. Later we are going to use PNGs for discs for transparency purpose.

Now, let's make it appears on our game:
* upload board.jpg in your "img/" directory.
* edit "reversi_reversi.tpl" to add a 'div' for your board:

<pre>
<div id="board">
</div>
</pre>

* edit your reversi.css file to transform it into a visible board:

#board {
width: 536px;
height: 528px;
background-image: url('../../img/reversi/board.jpg');
}

Refresh your page. Here's your board:

[[File:reversi1.jpg]]

== Make the squares appears ==

Now, what we need is to create some invisible HTML elements where squares are. These elements will be used as position references for width and black discs.
Obviously, we need 64 squares. To avoid writing 64 'div' elements on our template, we are going to use the "block" feature.

Let's modify our template like this:

<pre>
<div id="board">

<div id="square_{X}_{Y}" class="square" style="left: {LEFT}px; top: {TOP}px;"></div>

</div>
</pre>

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.

Let's do it in our "reversi.view.php" file:

<pre>
$this->page->begin_block( "reversi_reversi", "square" );

$hor_scale = 64.8;
$ver_scale = 64.4;
for( $x=1; $x<=8; $x++ )
{
for( $y=1; $y<=8; $y++ )
{
$this->page->insert_block( "square", array(
'X' => $x,
'Y' => $y,
'LEFT' => round( ($x-1)*$hor_scale+10 ),
'TOP' => round( ($y-1)*$ver_scale+7 )
) );
}
}
</pre>

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.

Now, to finish our work and check if everything works fine, we are going to style our square a little bit in our CSS stylesheet:

<pre>
#board {
width: 536px;
height: 528px;
background-image: url('../../img/reversi/board.jpg');
position: relative;
}

.square {
width: 56px;
height: 56px;
position: absolute;
background-color: red;
}
</pre>

Explanations:
* With "position: relative" on board, we ensure square elements are positioned relatively to board.
* For the test, we use a red background color for the square. This is a useful tip to figure out if everything is fine with invisible elements.

Let's refresh and check our our (beautiful) squares:

[[File:reversi2.jpg]]

== The discs ==

Now, our board is ready to receive some disc tokens!

At first, we introduce a new 'div' element as a child of "board" to host all these tokens (in our template):

<pre>


<div id="tokens">
</div>
</div>
</pre>

Then, let's introduce a new piece of art with the discs. We need some transparency here so we are using a png file:

[[File:tokens.png]]

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].

Now, let's separate the disc with some CSS stuff:

<pre>
.token {
width: 56px;
height: 56px;
position: absolute;
background-image: url('../../img/reversi/tokens.png');
}
.tokencolor_ffffff { background-position: 0px 0px; }
.tokencolor_000000 { background-position: -56px 0px; }
</pre>

With this CSS code, we apply the classes "token" and "tokencolor_ffffff" to a div element and we've got a white token. Yeah.

Note the "position: absolute" which allows us to position tokens on the board and make them "slide" to their positions.

Now, let's make a first token appear on our board. Disc tokens are not visible at the beginning of the game: they appear dynamically during the game. For this reason, we are going to make them appear from our Javascript code, with a BGA Framework technique called "JS template".

In our template file (reversi_reversi.tpl), let's create the piece of HTML needed to display our token:

<pre>
<script type="text/javascript">

// Templates

var jstpl_disc='<div class="disc disccolor_${color}" id="disc_${xy}"></div>';

</script>
</pre>

Note: we already created the "templates" section for you in the game skeleton.

As you can see, we defined a JS template named "jstpl_disc" with a piece of HTML and two variables: the color of the token and its x/y coordinates. Note that the syntax of the argument is different for template block variables (brackets) and JS template variables (dollar and brackets).

Now, let's create a method in our Javascript code that will make a token appear on the board, using this template:

<pre>
addTokenOnBoard: function( x, y, player )
{
dojo.place( this.format_block( 'jstpl_token', {
xy: x+''+y,
color: this.gamedatas.players[ player ].color
} ) , 'tokens' );

this.placeOnObject( 'token_'+x+''+y, 'overall_player_board_'+player );
this.slideToObject( 'token_'+x+''+y, 'square_'+x+'_'+y ).play();
},
</pre>

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.

Then, with BGA "this.placeOnObject" method, we place this element over the panel of some player. Immediately after, using BGA "this.slidetoObject" method, we make the disc slide to the "square" element, its final destination.

Note: don't forget to call the "play()", otherwise the token remains at its original location.

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.

Now, to test if everything works fine, just call "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:

[[File:reversi3.jpg]]

== The database ==

We did most of the client-side programming, so let's have a look on the other side now.

To design the database model of our game, 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.

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.

[[File:reversi4.jpg]]

The database model of Reversi is very simple: just one table with the squares of the board. In our dbmodel.sql, we have this:

<pre>
CREATE TABLE IF NOT EXISTS `board` (
`board_x` smallint(5) unsigned NOT NULL,
`board_y` smallint(5) unsigned NOT NULL,
`board_player` int(10) unsigned DEFAULT NULL,
PRIMARY KEY (`board_x`,`board_y`)
) ENGINE=InnoDB;
</pre>

Now, a new database with a "board" table will be created each time we start a Reversi game. This is why after modifying our dbmodel.sql it's a good time to stop & start again our game.

== Setup the initial game position ==

The "setupNewGame" method of our reversi.game.php is called during initial setup: this is the place to initialize our data and to place the initial tokens on the board (initially, there are 4 tokens on the board).

Let's do this:

<pre>
// Init the board
$sql = "INSERT INTO board (board_x,board_y,board_player) VALUES ";
$sql_values = array();
for( $x=1; $x<=8; $x++ )
{
for( $y=1; $y<=8; $y++ )
{
$token_value = "NULL";
if( ($x==4 && $y==4) || ($x==5 && $y==5) ) // Initial positions of white player
$token_value = "'$whiteplayer_id'";
else if( ($x==4 && $y==5) || ($x==5 && $y==4) ) // Initial positions of black player
$token_value = "'$blackplayer_id'";

$sql_values[] = "('$x','$y',$token_value)";
}
}
$sql .= implode( $sql_values, ',' );
self::DbQuery( $sql );

// Active first player
self::activeNextPlayer();
</pre>

As you can see, we create one database entry for each square, with a "NULL" value which mean "empty square". Of course, for 4 specific squares, we place an initial token.

At the end, we active the first player to make it active at the beginning of the game.

Now, we need to make these tokens appears 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):

<pre>
// Get reversi board token
$result['board'] = self::getObjectListFromDB( "SELECT board_x x, board_y y, board_player player
FROM board
WHERE board_player IS NOT NULL" );
</pre>

As you can see, we are using the BGA framework "getObjectListFromDB" method that format the result of this SQL query in a PHP array with x, y and player attribute.

The last thing we need to do is to process this array on 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:

<pre>
for( var i in gamedatas.board )
{
var square = gamedatas.board[i];

if( square.player !== null )
{
this.addTokenOnBoard( square.x, square.y, square.player );
}
}
</pre>

As you can see, our "board" entry created in "getAllDatas" can be used here as "gamedatas.board" in our Javascript. We are using our previously developed "addTokenOnBoard" method.

Reload... and here we are:

[[File:reversi5.jpg]]

It starts to smell Reversi here...

== The game state machine ==

Now, let's stop our game again, because we are going to start the core game logic.

You already read the "Focus on BGA game state machine", so you know that this is the heart of your game logic. For reversi game, it's very simple although. Here's a diagram of our game state machine for Reversi:

[[File:reversi6.jpg]]

And here's our "stats.inc.php", according to this diagram:

<pre>
$machinestates = array(

1 => array(
"name" => "gameSetup",
"description" => clienttranslate("Game setup"),
"type" => "manager",
"action" => "stGameSetup",
"transitions" => array( "" => 10 )
),

10 => array(
"name" => "playerTurn",
"description" => clienttranslate('${actplayer} must play a disc'),
"descriptionmyturn" => clienttranslate('${you} must play a disc'),
"type" => "activeplayer",
"args" => "argPlayerTurn",
"possibleactions" => array( 'playDisc' ),
"transitions" => array( "playDisc" => 11, "zombiePass" => 11 )
),

11 => array(
"name" => "nextPlayer",
"type" => "game",
"action" => "stNextPlayer",
"updateGameProgression" => true,
"transitions" => array( "nextTurn" => 10, "cantPlay" => 11, "endGame" => 99 )
),

99 => array(
"name" => "gameEnd",
"description" => clienttranslate("End of game"),
"type" => "manager",
"action" => "stGameEnd",
"args" => "argGameEnd"
)

);
</pre>

Now, let's create in our reversi.game.php file the methods that are declared in this game states description file:
* argPlayerTurn
* stNextPlayer

... and start a new Reversi game.

As you can see on the screen capture below, the BGA framework makes the game jump to our first game state "playerTurn" right after the initial setup. That's why the status bar contains the description of playerTurn state ("XXXX must play a disc"):

[[File:reversi7.jpg]]

== The rules ==

Now, what we would like to do is to indicate to the current player where it is allowed to play. The idea is to build a "getPossibleMoves" PHP method that return a list of coordinates where it is allowed to play. This method will be used in particular:
* As we just said, to help the player to see where he can play.
* When the player play, to check if he has the right to play here.

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:
* 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.
* 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.

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.

If you want to look into details, please look at the "utility method" sections of reversi.game.php.

== Display allowed moves ==

Now, what we want to do is highlight squares where player can place a disc.

To do this, we are using the "argPlayerTurn" method. This method is called each time we enter into "playerTurn" game state, and its result is transfered automatically to the client-side:

<pre>

function argPlayerTurn()
{
return array(
'possibleMoves' => self::getPossibleMoves( self::getActivePlayerId() )
);
}
</pre>

We are of course using the "getPossibleMoves" method we just developed.

Now, let's go to the client side to use the data returned by the method above. We are using the "onEnteringState" Javascript method that is called each time we enter into a new game state:

<pre>
onEnteringState: function( stateName, args )
{
console.log( 'Entering state: '+stateName );

switch( stateName )
{
case 'playerTurn':
this.updatePossibleMoves( args.args.possibleMoves );
break;
}
},
</pre>

So, when we are entering into "playerTurn" game state, we are calling our "updatePossibleMoves" method. This method looks like this:

<pre>
updatePossibleMoves: function( possibleMoves )
{
// Remove current possible moves
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );

for( var x in possibleMoves )
{
for( var y in possibleMoves[ x ] )
{
// x,y is a possible move
dojo.addClass( 'square_'+x+'_'+y, 'possibleMove' );
}
}

this.addTooltipToClass( 'possibleMove', '', _('Place a disc here') );
},
</pre>

The idea here is that we've created a CSS class ("possibleMove") that can be applied to a "square" element to highlight it.

At first, we remove all "possibleMove" classes currently applied with the very useful combination of "dojo.query" and "removeClass" method.

Then we loop through all possible moves that our PHP "updatePossibleMoves" create for us, and add the "possibleMove" class to corresponding square.

Finally, we use BGA framework "addTooltipToClass" method to associate a tooltip to all these highlighted squares in order players can understand the meaning of this.

And here we are:

[[File:reversi8.jpg.jpg]]

== Let's play ==

From now, it's better to restart a game with 2 players, because we are going to implement a complete Reversi turn. The summary of what we are going to do is:
* When we click on a "possibleMove" square, send the move to the server.
* On server side, check the move is correct, apply Reversi rules and jump to next player.
* On client side, change the disc position to reflect the move.

Thus, what we do first is associate each click on a square to one of our method. We are doing this in our Javascript "setup" method:

<pre>
dojo.query( '.square' ).connect( 'onclick', this, 'onPlayDisc' );
</pre>

Note the use of the "dojo.query" method to get all HTML elements with "square" class in just one function call. Now, our "onPlayDisc" method is called each time someone click on a square.

Here's our "onPlayDisc" method below:

<pre>
onPlayDisc: function( evt )
{
// Stop this event propagation
dojo.stopEvent( evt );

// Get the cliqued square x and y
// Note: square id format is "square_X_Y"
var coords = evt.currentTarget.id.split('_');
var x = coords[1];
var y = coords[2];

if( ! dojo.hasClass( 'square_'+x+'_'+y, 'possibleMove' ) )
{
// This is not a possible move => the click does nothing
return ;
}

if( this.checkAction( 'playDisc' ) ) // Check that this action is possible at this moment
{
this.ajaxcall( "/reversi/reversi/playDisc.html", {
x:x,
y:y
}, this, function( result ) {} );
}
},
</pre>

What we do here is:
* We stop the propagation of the Javascript "onclick" event. Otherwise, it can lead to random behavior so it always a good idea.
* We get the x/y coordinates of the square by using "evt.currentTarget.id".
* We check that clicked square has the "possibleMove" class, otherwise we know for sure that we can't play there.
* We check that "playDisc" action is possible, according to current game state (see "possibleactions" entry in our "playerTurn" game state defined above). This check is important to avoid issues if a player double clicks on a square.
* Finally, we make a call to the server using BGA "ajaxcall" method with argument x and y.

Now, we have to manage this "playDisc" action on server side. At first, we introduce a "playDisc" entry point in our "reversi.action.php":

<pre>
public function playDisc()
{
self::setAjaxMode();
$x = self::getArg( "x", AT_posint, true );
$y = self::getArg( "y", AT_posint, true );
$result = $this->game->playDisc( $x, $y );
self::ajaxResponse( );
}
</pre>

As you can see, we get the 2 arguments x and y from the javascript call, and call a corresponding "playDisc" method in our game logic.

Now, let's have a look of this playDisc method:

<pre>
function playDisc( $x, $y )
{
// Check that this player is active and that this action is possible at this moment
self::checkAction( 'playDisc' );
</pre>

... at first, we check that this action is possible according to current game state (see "possible action"). We already did it on client side, but it's important to do it on server side too (otherwise it would be possible to cheat).

<pre>
// Now, check if this is a possible move
$board = self::getBoard();
$turnedOverDiscs = self::getTurnedOverDiscs( $x, $y, $player_id, $board );

if( count( $turnedOverDiscs ) > 0 )
{
// This move is possible!
</pre>

...now, we are using the "getTurnedOverDiscs" method again to check that this move is possible.

<pre>
// Let's place a disc at x,y and return all "$returned" discs to the active player

$sql = "UPDATE board SET board_player='$player_id'
WHERE ( board_x, board_y) IN ( ";

foreach( $turnedOverDiscs as $turnedOver )
{
$sql .= "('".$turnedOver['x']."','".$turnedOver['y']."'),";
}
$sql .= "('$x','$y') ) ";

self::DbQuery( $sql );

</pre>

... we update the database to change the color of all turned over disc + the disc we just placed.

<pre>
// Update scores according to the number of disc on board
$sql = "UPDATE player
SET player_score = (
SELECT COUNT( board_x ) FROM board WHERE board_player=player_id
)";
self::DbQuery( $sql );

// Statistics
self::incStat( count( $turnedOverDiscs ), "turnedOver", $player_id );
if( ($x==1 && $y==1) || ($x==8 && $y==1) || ($x==1 && $y==8) || ($x==8 && $y==8) )
self::incStat( 1, 'discPlayedOnCorner', $player_id );
else if( $x==1 || $x==8 || $y==1 || $y==8 )
self::incStat( 1, 'discPlayedOnBorder', $player_id );
else if( $x>=3 && $x<=6 && $y>=3 && $y<=6 )
self::incStat( 1, 'discPlayedOnCenter', $player_id );

</pre>

... now, we update both player score by counting all disc, and we manage game statistics.

<pre>
// Notify
self::notifyAllPlayers( "playDisc", clienttranslate( '${player_name} plays a disc and turns over ${returned_nbr} disc(s)' ), array(
'player_id' => $player_id,
'player_name' => self::getActivePlayerName(),
'returned_nbr' => count( $turnedOverDiscs ),
'x' => $x,
'y' => $y
) );

self::notifyAllPlayers( "turnOverDiscs", '', array(
'player_id' => $player_id,
'turnedOver' => $turnedOverDiscs
) );

$newScores = self::getCollectionFromDb( "SELECT player_id, player_score FROM player", true );
self::notifyAllPlayers( "newScores", "", array(
"scores" => $newScores
) );
</pre>

... then we notify about all these changes. We are using for that 3 notifications ('playDisc', 'turnOverDiscs' and 'newScores' that we are going to implement on client side later). Note that the description of the 'playDisc' notification will be logged in the game log.

<pre>
// Then, go to the next state
$this->gamestate->nextState( 'playDisc' );
}
else
throw new feException( "Impossible move" );
}
</pre>

... finally, we jump to the next game state if everything goes fine ('playDisc' is also the name of a transition in the 'playerTurn' game state description above).

A last thing to do on the server side is to active the next player when we enter in the "nextPlayer" game state:

<pre>
function stNextPlayer()
{
// Active next player
$player_id = self::activeNextPlayer();

self::giveExtraTime( $player_id );
$this->gamestate->nextState( 'nextTurn' );

}
</pre>

Now, when we play a disc, the rules are checked and the disc appears in the database.

[[File:reversi9.jpg]]

Of course, as we don't manage notifications on client side, we need to press F5 after each move to see the changes on the board.

== Make the move appears automatically ==

Now, what we have to do is process the notifications sent by the server and make the move appear on the interface.

In our "setupNotifications" method, we register 2 methods for the 2 notifications we created at the previous step ('playDisc' and 'turnOverDiscs'):

<pre>
dojo.subscribe( 'playDisc', this, "notif_playDisc" );
this.notifqueue.setSynchronous( 'playDisc', 500 );
dojo.subscribe( 'turnOverDiscs', this, "notif_turnOverDiscs" );
this.notifqueue.setSynchronous( 'turnOverDiscs', 1500 );
</pre>

As you can see, we associate our 2 notifications with 2 methods with the "notif_" prefix. At the same time, we define these notifications as "synchronous", with a duration in millisecond (500 for the first one, and 1500 for the second one). It tells the user interface to wait some time after executing the notification, to let the animation end before starting the next notification. In our specific case, the animation will be the following:
* Make a disc slide from the player panel to its place on the board
* (wait 500ms)
* Make all turned over discs blink (and of course turned them over)
* (wait 1500ms)
* Let the next player play.

Let's have a look now on the "playDisc" notification handler method:

<pre>
notif_playDisc: function( notif )
{
// Remove current possible moves (makes the board more clear)
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );

this.addDiscOnBoard( notif.args.x, notif.args.y, notif.args.player_id );
},
</pre>

No surprise here, we re-used some existing stuff to:
* Remove the highlighted squares.
* Add a new disc on board, coming from player panel.

Now, here's the method that handle the turnOverDiscs notification:

<pre>
notif_turnOverDiscs: function( notif )
{
// Get the color of the player who is returning the discs
var targetColor = this.gamedatas.players[ notif.args.player_id ].color;

// Made these discs blinking and set them to the specified color
for( var i in notif.args.turnedOver )
{
var disc = notif.args.turnedOver[ i ];

// Make the disc blink 2 times
var anim = dojo.fx.chain( [
dojo.fadeOut( { node: 'disc_'+disc.x+''+disc.y } ),
dojo.fadeIn( { node: 'disc_'+disc.x+''+disc.y } ),
dojo.fadeOut( {
node: 'disc_'+disc.x+''+disc.y,
onEnd: function( node ) {

// Remove any color class
dojo.removeClass( node, [ 'disccolor_000000', 'disccolor_ffffff' ] );
// ... and add the good one
dojo.addClass( node, 'disccolor_'+targetColor );

}
} ),
dojo.fadeIn( { node: 'disc_'+disc.x+''+disc.y } )

] ); // end of dojo.fx.chain

// ... and launch the animation
anim.play();
}
},
</pre>

The list of the discs 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 it. The complete documentation on dojo animations [http://dojotoolkit.org/documentation/tutorials/1.6/animation/ can be found here].

In few words: we create a chain of 4 animations to make the disc fade out, fade in, fade out again, and fade in again. At the end of the second fade out, we change the color of the disc. Finally, we launch the animation with "play()".