Board Game Arena - User contributions [en]

Tutorial reversi

2026-03-30T20:11:17Z

RichardSPeters: removing confusion re PlayerTurn and PlayDisc (php and js)

== Introduction ==

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

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

== Create your first game ==

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

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

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

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

== Editing the game information (Optional) ==

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

==== Edits to fix Errors ====
* Edit your local copy of the <code>gameinfos.inc.php</code> file:
** Change the <code>bgg_id</code> value from <code>0</code> to <code>2389</code> - that's around line 26.
** Add <code>1,</code> to the players array (so you can start 1-player games while testing) - that's around line 29.
* Upload the <code>gameinfos.inc.php</code> file to the SFTP server (see [[First_steps_with_BGA_Studio#Connect_to_your_SFTP_folder|Connect to your SFTP folder]]).

==== Test your Edits ====
* Go back to your project page, and in the the local version, click Game page and check if the information match what you changed in the gameinfos file. [[File:Studio local version block.png|frameless]]

===== Not working? =====
Some changes will require bypassing the cache (adding/changing images). It is often worth doing a hard refresh (Ctrl+F5) to make sure the latest version is used.

== Make sure the IDE is properly configured ==
Try to add some invalid values in the framework names like this :

[[File:Voluntary reversi tutorial ide error.png]]

The error should be underlined if your IDE is properly configured. If it is not, check [[Setting up BGA Development environment using VSCode]]

In the same fashion, the autocomplete of the IDE should propose you some values after <code>this->bga-></code>.

You can also check if the upload works as expected, the game should now work and display the error (Undefined property: Bga\Games\EmptyGame\Game::$bgaTEST ...).

Revert to the correct syntax.

== Make it look like Reversi ==

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

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

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

[[File:Board.jpg]]

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

==== Add the board ====
use lowercase file names
* upload <code>board.jpg</code> in your <code>img/</code> directory.
* edit <code>modules/js/Game.js</code> to add the <code>div</code> for your board at the beginning of the setup function.

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

Edit the Game.js file and replace the code after '''// Example to add a div on the game area''' with the following:
<pre>
this.bga.gameArea.getElement().insertAdjacentHTML('beforeend', `
<div id="board">
</div>
`);
</pre>

Note: example above use backticks, aka string template literals. This technique used a lot in code of games as it allows to easily create html with strings substitutions, use quotes, double quotes and newlines.
If you don't know what it is check here
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals

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

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

and remove the code in Game.js in method onEnteringState that refers to adding action buttons and remove the section under <code>// example of adding a div for each player"</code>.

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

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

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

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

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

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

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

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

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

.square {
width: 62px;
height: 62px;
position: absolute;
background-color: red;
display: flex;
justify-content: center;
align-items: center;
}
</pre>

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

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

[[File:reversi2.jpg]]

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

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

==The Tokens==

Now, our board is ready for some tokens!

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

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

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

[[File:tokens.png]]

Upload this image file <code>tokens.png</code> in your <code>img/</code> directory. NB: may need to manually upload as have found that the automatic SFTP does't seem to pick up images.

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

====Style the Tokens in .css file ====
<pre>
.disc {
position: relative;
width: 54px;
height: 54px;
z-index: 3;
transform-style: preserve-3d;
}
.disc .disc-faces {
transform-style: preserve-3d;
}
.disc[data-color="000000"] .disc-faces {
transform: rotateY(180deg);
}

.disc-face {
position: absolute;
width: 54px;
height: 54px;
background-image: url('img/tokens.png');
background-size: auto 100%;
backface-visibility: hidden;
}
.disc-face[data-side="white"] {
background-position-x: 0%;
transform: rotateY(0deg);
}
.disc-face[data-side="black"] {
background-position-x: 100%;
transform: rotateY(180deg);
}
</pre>

With this CSS code, we can set and change the token color by changing the <code>data-color</code> attribute. Using data instead of a class ensures it can be only one of them (the disc cannot be black and white at the same time).
We will create a disc-faces div in the disc containing 2 disc-face divs, to represent each face of the disc. It will allow us to have a nice flip animation!

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

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

<pre>
async addDiscOnBoard( x, y, playerId, animate = true )
{
const color = this.gamedatas.players[ playerId ].color;
const discId = `disc_${x}_${y}`;

document.getElementById(`square_${x}_${y}`).insertAdjacentHTML('beforeend', `
<div class="disc" data-color="${color}" id="${discId}">
<div class="disc-faces">
<div class="disc-face" data-side="white"></div>
<div class="disc-face" data-side="black"></div>
</div>
</div>
`);

if (animate) {
const element = document.getElementById(discId);
await this.animationManager.fadeIn(element, document.getElementById(`overall_player_board_${playerId}`));
}
}
</pre>

For this to work, you will also need to initialize the animation manager. Include the function in your .js file by updating as outlined here: [[BgaAnimations]]. Then add this in the setup function:
<pre>

this.animationManager = new BgaAnimations.Manager({
animationsActive: () => this.bga.gameui.bgaAnimationsActive(),
});
</pre>

=====Utility Method Explanation=====
*with <code>element.insertAdjacentHTML</code> method, we create a HTML piece of code and insert it as a new child of the square div element.
*Immediately after, using <code>this.animationManager.fadeIn</code> BGA method, we make the disc slide in (with a fade in animation) from the player panel.

Also note the trailing comma - this is needed because there may be other functions defined after this one, making <code>addDiscOnBoard</code> just one element in an array of functions.

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

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

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

===Test the Token===
Now, to test if everything works fine we will call the <code>addTokenOnBoard()</code> in .js file to Test

In <code>modules/js/Game.js</code>, in the <code>setup</code> function, under the code we added to generate the squares.
this.addDiscOnBoard(2, 2, this.bga.players.getCurrentPlayerId(), false);
Now restart the game.

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

[[File:reversi3.jpg]]

==The database==

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

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

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

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

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

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

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

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

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

Start a new game and verify a table is created : Click the "Go to game database", use the login and password your received by email, then you should see <code>board</code> in the list of tables (the db of the current table is automatically selected when clicking on this button).

== Setup the initial game position ==

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

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

===Initialize the Board in modules/php/Game.php file===
Under <code>// TODO: setup the initial game situation here</code>, initialize the board
<pre>
list( $blackplayer_id, $whiteplayer_id ) = array_keys( $players );
// Init the board
$this->boardManager->initializeBoard(8, (int) $blackplayer_id, (int) $whiteplayer_id);
</pre>

Wait, is that all?

No, the boardManager doesn't exist, we'll create it so it will handle all the functions related the tokens on the board. Splitting the code in multiple files will help us have easier to read classes, even more if each class handle a specific responsability.

Create a BoardManager.php file next to Game.php, and put this code in it:
<pre>
<?php
declare(strict_types=1);

namespace Bga\Games\Reversi;

class BoardManager
{
public function __construct(private Game $game)
{
}

public function initializeBoard(int $boardSize, int $blackPlayerId, int $whitePlayerId): void
{
$sqlValues = [];
$boardSizeHalf = (int) floor($boardSize / 2);

for ($x = 1; $x <= $boardSize; $x++) {
for ($y = 1; $y <= $boardSize; $y++) {
$discValue = 'NULL';
if (($x === $boardSizeHalf && $y === $boardSizeHalf) || ($x === ($boardSizeHalf + 1) && $y === ($boardSizeHalf + 1))) {
$discValue = (string) $whitePlayerId;
} elseif (($x === $boardSizeHalf && $y === ($boardSizeHalf + 1)) || ($x === ($boardSizeHalf + 1) && $y === $boardSizeHalf)) {
$discValue = (string) $blackPlayerId;
}

$sqlValues[] = "($x,$y,$discValue)";
}
}

$sql = "INSERT INTO `board` (`board_x`,`board_y`,`board_player`) VALUES " . implode(',', $sqlValues);
$this->game->DbQuery($sql);
}
}
</pre>

Once the php file is created edit the namespace and change \Reversi to be the name of your project

Note: the file name match the class name, and the namespace will now match the one from Game.php (so we are following PSR-4 specification), allowing BGA to autoload the class when we will need it. Let's initialize it from the Game.php file!

Before the Game __construct, add
<pre>
public BoardManager $boardManager;
</pre>

At the end of the Game __construct, add
<pre>
$this->boardManager = new BoardManager($this);
</pre>

Passing the game object to the constructor allows us to use its db functions.

If we were managing cards, we would have probably used the [[Deck]] component, and ideally we would create a CardManager that holds the Deck and all game specific logic about managing the cards.

==== Board Initialization Explanation ====

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

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

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

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

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

<pre>
// Get reversi board token
$result['board'] = $this->boardManager->getOccupiedDiscs();
</pre>
And in the board manager, add:
<pre>
public function getOccupiedDiscs(): array
{
return $this->game->getObjectListFromDB(
"SELECT `board_x` `x`, `board_y` `y`, `board_player` `player`
FROM `board`
WHERE `board_player` IS NOT NULL"
);
}
</pre>

Next, you will modify the query that gets player information to also get the player's colors. Above the lines you just inserted in <code>getAllDatas()</code> notice how we've added <code>player_color color</code> to the sql query in the code below.

<pre>
$result["players"] = $this->getCollectionFromDb(
"SELECT `player_id` `id`, `player_score` `score`, `player_color` `color` FROM `player`"
);
</pre>

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

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

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

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

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

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

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

[[File:reversi5.jpg]]

It starts to feel like Reversi here...

==State Machine==

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

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

[[File:reversi6.jpg]]

===Build your States===
And here are the classes we need to create on the <code>module/php/States</code> folder, according to this diagram (note - PlayerTurn is replaced by PlayDisc):

'''PlayDisc.php:'''
<pre>
<?php

declare(strict_types=1);

namespace Bga\Games\Reversi\States;

use Bga\GameFramework\StateType;
use Bga\Games\Reversi\Game;

class PlayDisc extends \Bga\GameFramework\States\GameState
{
public function __construct(protected Game $game) {
parent::__construct($game,
id: 10,
type: StateType::ACTIVE_PLAYER,

description: clienttranslate('${actplayer} must play a disc'),
descriptionMyTurn: clienttranslate('${you} must play a disc'),
);
}

function zombie(int $playerId) {
}
}
</pre>

(The ''declare(strict_types=1)'' is optional but recommended for new games). The ''<?php'' at the beginning is necessary for your IDE to understand the php syntax. )

In PlayDisc.js remove the code in onEnteringState (which sets the title top you/activealayer must play a counter

'''NextPlayer.php:'''
<pre>
<?php

declare(strict_types=1);

namespace Bga\Games\Reversi\States;

use Bga\GameFramework\StateType;
use Bga\Games\Reversi\Game;

class NextPlayer extends \Bga\GameFramework\States\GameState
{

public function __construct(protected Game $game) {
parent::__construct($game,
id: 90,
type: StateType::GAME,

updateGameProgression: true,
);
}
}
</pre>
Note: state ids 1 and 99 are reserved by the framework for gameSetup and gameEnd. We don't need to describe those states as the framework will take care of that for us.

In setupNewGame in Game.php, make sure the return is <code>return PlayDisc::class;</code> so the framework knows which game state is the initial one.

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

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

[[File:reversi7.jpg]]

==The rules==

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

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

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

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

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

==Display allowed moves==

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

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

<pre>
function getArgs(int $activePlayerId): array
{
return [
'possibleMoves' => $this->game->boardManager->getPossibleMoves($activePlayerId)
];
}
</pre>

Now we need to handle it on the JS side.
Replace the state classes definition in the Game constructor by this:
<pre>
// Declare the State classes
this.playDisc = new PlayDisc(this, bga);
this.bga.states.register('PlayDisc', this.playDisc);
</pre>
So it matches the state we described in PHP. The state name is the PHP class name, that we use in register to link them.

Replace the class PlayerTurn in <code>modules/js/Game.js</code> by this one:
<pre>
class PlayDisc {
constructor(game, bga) {
this.game = game;
this.bga = bga;
}

onEnteringState(args, isCurrentPlayerActive) {
this.bga.statusBar.setTitle(isCurrentPlayerActive ?
_('${you} must play a disc') :
_('${actplayer} must play a disc')
);

if (isCurrentPlayerActive) {
this.updatePossibleMoves(args.possibleMoves);
}
}
}
</pre>

<b>Note:</b> We set the title when entering the state, so you can now remove description/descriptionMyTurn in the PHP class that was just here for test purpose.

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

Each time we enter into a new game state, we use the <code>onEnteringState</code> Javascript method of the JS State class. This lets us use the data returned by the method above on the client side.

So, when we enter into <code>PlayDisc</code> game state, we call our <code>updatePossibleMoves</code> method (under the "Utility methods" section). This method is added to PlayDisc class and looks like this:
<pre>
updatePossibleMoves(possibleMoves) {
// Remove current possible moves
document.querySelectorAll('.possibleMove').forEach(div => div.classList.remove('possibleMove'));

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

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

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

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

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

And here we are:

[[File:reversi8.jpg.jpg]]

==Let's play ==

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

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

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

Now, our "onPlayDisc" method is called each time someone clicks on a square.

Here's our "onPlayDisc" method below:

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

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

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

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

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

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

<pre>
#[PossibleAction]
function actPlayDisc( int $x, int $y, int $activePlayerId )
{
</pre>
And add <code>use Bga\GameFramework\States\PossibleAction;</code> at the top of the file.

(The function will be called when the front-side action is triggered using the Autowire mechanism, if you want to see how it works in details check [[Main game logic: Game.php|https://en.doc.boardgamearena.com/Main_game_logic:_Game.php#Actions_%28autowired%29]] )

now, we are using the <code>getTurnedOverDiscs</code> method again to check that this move is possible:
<pre>
// Now, check if this is a possible move
$board = $this->game->boardManager->getBoard();
$turnedOverDiscs = $this->game->getTurnedOverDiscs( $x, $y, $activePlayerId, $board );

if( count( $turnedOverDiscs ) === 0 ) {
throw new SystemException("Impossible move");
}
</pre>

we update the database to change the color of all turned over disc + the disc we just placed:
<pre>
// Let's place a disc at x,y and return all "$returned" discs to the active player

$this->game->boardManager->applyMove($activePlayerId, $x, $y, $turnedOverDiscs);
</pre>

We add this part to the BoardManager before going back to our act function:
<pre>
public function applyMove(int $playerId, int $x, int $y, array $turnedOverDiscs): void
{
$positions = [];
foreach ($turnedOverDiscs as $turnedOver) {
$turnedX = (int) $turnedOver['x'];
$turnedY = (int) $turnedOver['y'];
$positions[] = "($turnedX,$turnedY)";
}
$positions[] = "($x,$y)";

$sql = "UPDATE `board` SET `board_player` = $playerId WHERE (`board_x`, `board_y`) IN (" . implode(',', $positions) . ")";
$this->game->DbQuery($sql);
}
</pre>

define what game statistics we want to record (for more details read [[Game statistics: stats.json]]), For this tutorial we need to edit the stats.json file and set it to the following:
{
"table": [],
"player": {
"discPlayedOnCorner": {
"id": 10,
"name": "Discs played on a corner",
"type": "int"
},
"discPlayedOnBorder": {
"id": 11,
"name": "Discs played on a border",
"type": "int"
},
"discPlayedOnCenter": {
"id": 12,
"name": "Discs played on board center part",
"type": "int"
},
"turnedOver": {
"id": 13,
"name": "Number of discs turned over",
"type": "int"
}
}
}
we manage game statistics:
<pre>
$this->bga->playerStats->inc('turnedOver', $disc_count, $activePlayerId);
$updatedStat = 'discPlayedOnCenter';
if( ($x==1 && $y==1) || ($x==$board_size && $y==1) || ($x==1 && $y==$board_size) || ($x==$board_size && $y==$board_size) ) {
$updatedStat = 'discPlayedOnCorner';
} else if( $x==1 || $x==$board_size || $y==1 || $y==$board_size ) {
$updatedStat = 'discPlayedOnBorder';
}
$this->bga->playerStats->inc($updatedStat, 1, $activePlayerId);
</pre>

Notify the turned discs:
<pre>
// Notify
$this->bga->notify->all( "playDisc", clienttranslate( '${player_name} plays a disc and turns over ${returned_nbr} disc(s)' ), array(
'player_id' => $activePlayerId,
'player_name' => $this->game->getPlayerNameById($activePlayerId),
'returned_nbr' => count( $turnedOverDiscs ),
'x' => $x,
'y' => $y
) );

$this->bga->notify->all( "turnOverDiscs", '', array(
'player_id' => $activePlayerId,
'turnedOver' => $turnedOverDiscs
) );
</pre>

Then we update the scores accordingly
<pre>
$playerIds = array_keys($this->game->loadPlayersBasicInfos());
foreach ($playerIds as $playerId) {
$tokens = $this->game->boardManager->countDiscsForPlayer((int) $playerId);
$this->bga->playerScore->set($playerId, $tokens); // this will update the JS counter automatically
}
</pre>

In BoardManager, add:
<pre>
public function countDiscsForPlayer(int $playerId): int
{
return (int) $this->game->getUniqueValueFromDB("SELECT COUNT(*) FROM `board` WHERE `board_player` = $playerId");
}
</pre>

We are using for that 2 notifications (<code>playDisc</code> and <code>turnOverDiscs</code> that we are going to implement on client side later). Note that the description of the <code>playDisc</code> notification will be logged in the game log.

Finally, we jump to the next game state.
<pre>
// Then, go to the next state
return NextPlayer::class;
</pre>

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

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

A last thing to do on the server side is to activate the next player when we enter the <code>NextPlayer</code> game state (in the <code>modules/php/States/NextPlayer.php</code> file):

Add `const ST_END_GAME = 99;` at the top of the file, then add:

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

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

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

// Can this player play?

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

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

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

[[File:reversi9.jpg]]

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

==Make the move appear automatically==

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

In our <code>setupNotifications</code> method in <code>modules/js/Game.js</code>, we tell BGA to listen to notifications we will add later (<code>playDisc</code> and <code>turnOverDiscs</code>) using promise-based notifications:

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

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

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

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

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

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

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

<pre>
async animateTurnOverDisc(disc, targetColor) {
const squareDiv = document.getElementById(`square_${disc.x}_${disc.y}`);
const discDiv = document.getElementById(`disc_${disc.x}_${disc.y}`);

squareDiv.classList.add('flip-animation');
await this.bga.gameui.wait(500); // for the flip animation to finish

discDiv.dataset.color = targetColor;

const parallelAnimations = [{
keyframes: [ // flip the disc
{ transform: `rotateY(180deg)` },
{ transform: `rotateY(0deg)` },
]
}, {
keyframes: [ // lift the disc
{ transform: `translate(0, -12px) scale(1.2)`, offset: 0.5 },
]
}];

await this.animationManager.slideAndAttach(discDiv, squareDiv, { duration: 1000, parallelAnimations });

squareDiv.classList.remove('flip-animation');
await this.bga.gameui.wait(500); // for the flip animation removal to finish
}

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

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

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

We create a chain of 3 animations using await to make the square highlight, then flip the token, then remove the square highlight.

==Implement the zombie mode ==
When a player leave the table, a Zombie (bot) will play for the leaver, so the table can continue. For that, we write code in the zombieTurn function.

to learn more about the Zombie mode, read [[Zombie Mode]]

Add this at the end of your PlayDisc.php file :
<pre>
function zombie(int $playerId) {
// Zombie level 1
$possibleMoves = $this->game->boardManager->getPossibleMoves($playerId);
// transform the 2 dimensional array into a flat array of possible [$x, $y]
$possibleMovesArray = [];
foreach($possibleMoves as $x => $ys) {
foreach($ys as $y => $valid) {
$possibleMovesArray[] = [$x, $y];
}
}

$zombieChoice = $this->getRandomZombieChoice($possibleMovesArray);
return $this->actPlayDisc($zombieChoice[0], $zombieChoice[1], $playerId);
}
</pre>

And that's it ! Everytime a leaver should be playing, the Zombie will random play one of the possible moves, and the remaining player will be able to play the next move.

== Add a debug function to help up test the code==
Add this at the end of your Game.php file :
<pre>

function debug_playAutomatically(int $moves = 50) {
$this->bga->debug->playUntil(fn(int $count) => $count === $moves);
}

function debug_playToEndGame() {
$this->debug_playAutomatically(64); // reversi max moves is under 64 for the standard size board
}
</pre>
This function plays automatically until we reach the end of the game. The functions starting with "debug_" can be triggered in the Studio with a special menu.
It uses the tool <code>$this->debug->playUntil</code> that will trigger zombie actions, but you could put any code in the debug function for the tests you need.

Start a new game, click on the Bug icon on the top left then "playToEndGame". You should see the game randomly playing until it reaches the end game, so it helps you check the animations, and you can see if the final scoring is also working as expected. This example will allow us to easily test the Zombie code, as it will play as a Zombie for all players until the end of the game. It's also an easy way to see if end score computation is working as expected!

You can create as many debug function as you like!

==Optional: add unit tests==
Follow the instruction on https://en.doc.boardgamearena.com/Testing_by_developer#PHP to setup phpunit and create the first Reversi unit tests that are given as examples there.

Running <code>phpunit</code>, it should be 4/4 OK! And we have a good hint the case of the full board should be handled OK without actually completing a game :)

==After the tutorial==
You might want to check another tutorial, or start working on your first real project !

[[Create a game in BGA Studio: Complete Walkthrough]]
[[Category:Studio]]

Tutorial reversi

2026-03-26T22:27:55Z

RichardSPeters: added notes re stats.json

== Introduction ==

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

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

== Create your first game ==

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

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

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

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

== Editing the game information (Optional) ==

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

==== Edits to fix Errors ====
* Edit your local copy of the <code>gameinfos.inc.php</code> file:
** Change the <code>bgg_id</code> value from <code>0</code> to <code>2389</code> - that's around line 26.
** Add <code>1,</code> to the players array (so you can start 1-player games while testing) - that's around line 29.
* Upload the <code>gameinfos.inc.php</code> file to the SFTP server (see [[First_steps_with_BGA_Studio#Connect_to_your_SFTP_folder|Connect to your SFTP folder]]).

==== Test your Edits ====
* Go back to your project page, and in the the local version, click Game page and check if the information match what you changed in the gameinfos file. [[File:Studio local version block.png|frameless]]

===== Not working? =====
Some changes will require bypassing the cache (adding/changing images). It is often worth doing a hard refresh (Ctrl+F5) to make sure the latest version is used.

== Make sure the IDE is properly configured ==
Try to add some invalid values in the framework names like this :

[[File:Voluntary reversi tutorial ide error.png]]

The error should be underlined if your IDE is properly configured. If it is not, check [[Setting up BGA Development environment using VSCode]]

In the same fashion, the autocomplete of the IDE should propose you some values after <code>this->bga-></code>.

You can also check if the upload works as expected, the game should now work and display the error (Undefined property: Bga\Games\EmptyGame\Game::$bgaTEST ...).

Revert to the correct syntax.

== Make it look like Reversi ==

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

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

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

[[File:Board.jpg]]

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

==== Add the board ====
use lowercase file names
* upload <code>board.jpg</code> in your <code>img/</code> directory.
* edit <code>modules/js/Game.js</code> to add the <code>div</code> for your board at the beginning of the setup function.

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

Edit the Game.js file and replace the code after '''// Example to add a div on the game area''' with the following:
<pre>
this.bga.gameArea.getElement().insertAdjacentHTML('beforeend', `
<div id="board">
</div>
`);
</pre>

Note: example above use backticks, aka string template literals. This technique used a lot in code of games as it allows to easily create html with strings substitutions, use quotes, double quotes and newlines.
If you don't know what it is check here
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals

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

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

and remove the code in Game.js in method onEnteringState that refers to adding action buttons and remove the section under <code>// example of adding a div for each player"</code>.

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

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

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

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

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

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

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

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

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

.square {
width: 62px;
height: 62px;
position: absolute;
background-color: red;
display: flex;
justify-content: center;
align-items: center;
}
</pre>

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

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

[[File:reversi2.jpg]]

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

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

==The Tokens==

Now, our board is ready for some tokens!

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

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

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

[[File:tokens.png]]

Upload this image file <code>tokens.png</code> in your <code>img/</code> directory. NB: may need to manually upload as have found that the automatic SFTP does't seem to pick up images.

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

====Style the Tokens in .css file ====
<pre>
.disc {
position: relative;
width: 54px;
height: 54px;
z-index: 3;
transform-style: preserve-3d;
}
.disc .disc-faces {
transform-style: preserve-3d;
}
.disc[data-color="000000"] .disc-faces {
transform: rotateY(180deg);
}

.disc-face {
position: absolute;
width: 54px;
height: 54px;
background-image: url('img/tokens.png');
background-size: auto 100%;
backface-visibility: hidden;
}
.disc-face[data-side="white"] {
background-position-x: 0%;
transform: rotateY(0deg);
}
.disc-face[data-side="black"] {
background-position-x: 100%;
transform: rotateY(180deg);
}
</pre>

With this CSS code, we can set and change the token color by changing the <code>data-color</code> attribute. Using data instead of a class ensures it can be only one of them (the disc cannot be black and white at the same time).
We will create a disc-faces div in the disc containing 2 disc-face divs, to represent each face of the disc. It will allow us to have a nice flip animation!

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

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

<pre>
async addDiscOnBoard( x, y, playerId, animate = true )
{
const color = this.gamedatas.players[ playerId ].color;
const discId = `disc_${x}_${y}`;

document.getElementById(`square_${x}_${y}`).insertAdjacentHTML('beforeend', `
<div class="disc" data-color="${color}" id="${discId}">
<div class="disc-faces">
<div class="disc-face" data-side="white"></div>
<div class="disc-face" data-side="black"></div>
</div>
</div>
`);

if (animate) {
const element = document.getElementById(discId);
await this.animationManager.fadeIn(element, document.getElementById(`overall_player_board_${playerId}`));
}
}
</pre>

For this to work, you will also need to initialize the animation manager. Include the function in your .js file by updating as outlined here: [[BgaAnimations]]. Then add this in the setup function:
<pre>

this.animationManager = new BgaAnimations.Manager({
animationsActive: () => this.bga.gameui.bgaAnimationsActive(),
});
</pre>

=====Utility Method Explanation=====
*with <code>element.insertAdjacentHTML</code> method, we create a HTML piece of code and insert it as a new child of the square div element.
*Immediately after, using <code>this.animationManager.fadeIn</code> BGA method, we make the disc slide in (with a fade in animation) from the player panel.

Also note the trailing comma - this is needed because there may be other functions defined after this one, making <code>addDiscOnBoard</code> just one element in an array of functions.

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

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

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

===Test the Token===
Now, to test if everything works fine we will call the <code>addTokenOnBoard()</code> in .js file to Test

In <code>modules/js/Game.js</code>, in the <code>setup</code> function, under the code we added to generate the squares.
this.addDiscOnBoard(2, 2, this.bga.players.getCurrentPlayerId(), false);
Now restart the game.

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

[[File:reversi3.jpg]]

==The database==

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

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

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

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

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

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

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

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

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

Start a new game and verify a table is created : Click the "Go to game database", use the login and password your received by email, then you should see <code>board</code> in the list of tables (the db of the current table is automatically selected when clicking on this button).

== Setup the initial game position ==

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

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

===Initialize the Board in modules/php/Game.php file===
Under <code>// TODO: setup the initial game situation here</code>, initialize the board
<pre>
list( $blackplayer_id, $whiteplayer_id ) = array_keys( $players );
// Init the board
$this->boardManager->initializeBoard(8, (int) $blackplayer_id, (int) $whiteplayer_id);
</pre>

Wait, is that all?

No, the boardManager doesn't exist, we'll create it so it will handle all the functions related the tokens on the board. Splitting the code in multiple files will help us have easier to read classes, even more if each class handle a specific responsability.

Create a BoardManager.php file next to Game.php, and put this code in it:
<pre>
<?php
declare(strict_types=1);

namespace Bga\Games\Reversi;

class BoardManager
{
public function __construct(private Game $game)
{
}

public function initializeBoard(int $boardSize, int $blackPlayerId, int $whitePlayerId): void
{
$sqlValues = [];
$boardSizeHalf = (int) floor($boardSize / 2);

for ($x = 1; $x <= $boardSize; $x++) {
for ($y = 1; $y <= $boardSize; $y++) {
$discValue = 'NULL';
if (($x === $boardSizeHalf && $y === $boardSizeHalf) || ($x === ($boardSizeHalf + 1) && $y === ($boardSizeHalf + 1))) {
$discValue = (string) $whitePlayerId;
} elseif (($x === $boardSizeHalf && $y === ($boardSizeHalf + 1)) || ($x === ($boardSizeHalf + 1) && $y === $boardSizeHalf)) {
$discValue = (string) $blackPlayerId;
}

$sqlValues[] = "($x,$y,$discValue)";
}
}

$sql = "INSERT INTO `board` (`board_x`,`board_y`,`board_player`) VALUES " . implode(',', $sqlValues);
$this->game->DbQuery($sql);
}
}
</pre>

Once the php file is created edit the namespace and change \Reversi to be the name of your project

Note: the file name match the class name, and the namespace will now match the one from Game.php (so we are following PSR-4 specification), allowing BGA to autoload the class when we will need it. Let's initialize it from the Game.php file!

Before the Game __construct, add
<pre>
public BoardManager $boardManager;
</pre>

At the end of the Game __construct, add
<pre>
$this->boardManager = new BoardManager($this);
</pre>

Passing the game object to the constructor allows us to use its db functions.

If we were managing cards, we would have probably used the [[Deck]] component, and ideally we would create a CardManager that holds the Deck and all game specific logic about managing the cards.

==== Board Initialization Explanation ====

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

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

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

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

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

<pre>
// Get reversi board token
$result['board'] = $this->boardManager->getOccupiedDiscs();
</pre>
And in the board manager, add:
<pre>
public function getOccupiedDiscs(): array
{
return $this->game->getObjectListFromDB(
"SELECT `board_x` `x`, `board_y` `y`, `board_player` `player`
FROM `board`
WHERE `board_player` IS NOT NULL"
);
}
</pre>

Next, you will modify the query that gets player information to also get the player's colors. Above the lines you just inserted in <code>getAllDatas()</code> notice how we've added <code>player_color color</code> to the sql query in the code below.

<pre>
$result["players"] = $this->getCollectionFromDb(
"SELECT `player_id` `id`, `player_score` `score`, `player_color` `color` FROM `player`"
);
</pre>

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

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

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

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

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

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

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

[[File:reversi5.jpg]]

It starts to feel like Reversi here...

==State Machine==

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

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

[[File:reversi6.jpg]]

===Build your States===
And here are the classes we need to create on the <code>module/php/States</code> folder, according to this diagram:

'''PlayerTurn.php:'''
<pre>
<?php

declare(strict_types=1);

namespace Bga\Games\Reversi\States;

use Bga\GameFramework\StateType;
use Bga\Games\Reversi\Game;

class PlayerTurn extends \Bga\GameFramework\States\GameState
{
public function __construct(protected Game $game) {
parent::__construct($game,
id: 10,
type: StateType::ACTIVE_PLAYER,

description: clienttranslate('${actplayer} must play a disc'),
descriptionMyTurn: clienttranslate('${you} must play a disc'),
);
}

function zombie(int $playerId) {
}
}
</pre>

(The ''declare(strict_types=1)'' is optional but recommended for new games). The ''<?php'' at the beginning is necessary for your IDE to understand the php syntax. )

In PlayerTurn.js remove the code in onEnteringState (which sets the title top you/activealayer must play a counter

'''NextPlayer.php:'''
<pre>
<?php

declare(strict_types=1);

namespace Bga\Games\Reversi\States;

use Bga\GameFramework\StateType;
use Bga\Games\Reversi\Game;

class NextPlayer extends \Bga\GameFramework\States\GameState
{

public function __construct(protected Game $game) {
parent::__construct($game,
id: 90,
type: StateType::GAME,

updateGameProgression: true,
);
}
}
</pre>
Note: state ids 1 and 99 are reserved by the framework for gameSetup and gameEnd. We don't need to describe those states as the framework will take care of that for us.

In setupNewGame in Game.php, make sure the return is <code>return PlayerTurn::class;</code> so the framework knows which game state is the initial one.

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

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

[[File:reversi7.jpg]]

==The rules==

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

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

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

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

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

==Display allowed moves==

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

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

<pre>
function getArgs(int $activePlayerId): array
{
return [
'possibleMoves' => $this->game->boardManager->getPossibleMoves($activePlayerId)
];
}
</pre>

Now we need to handle it on the JS side.
Replace the state classes definition in the Game constructor by this:
<pre>
// Declare the State classes
this.playDisc = new PlayDisc(this, bga);
this.bga.states.register('PlayDisc', this.playDisc);
</pre>
So it matches the state we described in PHP. The state name is the PHP class name, that we use in register to link them.

Replace the class PlayerTurn in <code>modules/js/Game.js</code> by this one:
<pre>
class PlayDisc {
constructor(game, bga) {
this.game = game;
this.bga = bga;
}

onEnteringState(args, isCurrentPlayerActive) {
this.bga.statusBar.setTitle(isCurrentPlayerActive ?
_('${you} must play a disc') :
_('${actplayer} must play a disc')
);

if (isCurrentPlayerActive) {
this.updatePossibleMoves(args.possibleMoves);
}
}
}
</pre>

<b>Note:</b> We set the title when entering the state, so you can now remove description/descriptionMyTurn in the PHP class that was just here for test purpose.

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

Each time we enter into a new game state, we use the <code>onEnteringState</code> Javascript method of the JS State class. This lets us use the data returned by the method above on the client side.

So, when we enter into <code>PlayDisc</code> game state, we call our <code>updatePossibleMoves</code> method (under the "Utility methods" section). This method is added to PlayDisc class and looks like this:
<pre>
updatePossibleMoves(possibleMoves) {
// Remove current possible moves
document.querySelectorAll('.possibleMove').forEach(div => div.classList.remove('possibleMove'));

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

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

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

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

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

And here we are:

[[File:reversi8.jpg.jpg]]

==Let's play ==

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

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

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

Now, our "onPlayDisc" method is called each time someone clicks on a square.

Here's our "onPlayDisc" method below:

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

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

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

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

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

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

<pre>
#[PossibleAction]
function actPlayDisc( int $x, int $y, int $activePlayerId )
{
</pre>
And add <code>use Bga\GameFramework\States\PossibleAction;</code> at the top of the file.

(The function will be called when the front-side action is triggered using the Autowire mechanism, if you want to see how it works in details check [[Main game logic: Game.php|https://en.doc.boardgamearena.com/Main_game_logic:_Game.php#Actions_%28autowired%29]] )

now, we are using the <code>getTurnedOverDiscs</code> method again to check that this move is possible:
<pre>
// Now, check if this is a possible move
$board = $this->game->boardManager->getBoard();
$turnedOverDiscs = $this->game->getTurnedOverDiscs( $x, $y, $activePlayerId, $board );

if( count( $turnedOverDiscs ) === 0 ) {
throw new SystemException("Impossible move");
}
</pre>

we update the database to change the color of all turned over disc + the disc we just placed:
<pre>
// Let's place a disc at x,y and return all "$returned" discs to the active player

$this->game->boardManager->applyMove($activePlayerId, $x, $y, $turnedOverDiscs);
</pre>

We add this part to the BoardManager before going back to our act function:
<pre>
public function applyMove(int $playerId, int $x, int $y, array $turnedOverDiscs): void
{
$positions = [];
foreach ($turnedOverDiscs as $turnedOver) {
$turnedX = (int) $turnedOver['x'];
$turnedY = (int) $turnedOver['y'];
$positions[] = "($turnedX,$turnedY)";
}
$positions[] = "($x,$y)";

$sql = "UPDATE `board` SET `board_player` = $playerId WHERE (`board_x`, `board_y`) IN (" . implode(',', $positions) . ")";
$this->game->DbQuery($sql);
}
</pre>

define what game statistics we want to record (for more details read [[Game statistics: stats.json]]), For this tutorial we need to edit the stats.json file and set it to the following:
{
"table": [],
"player": {
"discPlayedOnCorner": {
"id": 10,
"name": "Discs played on a corner",
"type": "int"
},
"discPlayedOnBorder": {
"id": 11,
"name": "Discs played on a border",
"type": "int"
},
"discPlayedOnCenter": {
"id": 12,
"name": "Discs played on board center part",
"type": "int"
},
"turnedOver": {
"id": 13,
"name": "Number of discs turned over",
"type": "int"
}
}
}
we manage game statistics:
<pre>
$this->bga->playerStats->inc('turnedOver', $disc_count, $activePlayerId);
$updatedStat = 'discPlayedOnCenter';
if( ($x==1 && $y==1) || ($x==$board_size && $y==1) || ($x==1 && $y==$board_size) || ($x==$board_size && $y==$board_size) ) {
$updatedStat = 'discPlayedOnCorner';
} else if( $x==1 || $x==$board_size || $y==1 || $y==$board_size ) {
$updatedStat = 'discPlayedOnBorder';
}
$this->bga->playerStats->inc($updatedStat, 1, $activePlayerId);
</pre>

Notify the turned discs:
<pre>
// Notify
$this->bga->notify->all( "playDisc", clienttranslate( '${player_name} plays a disc and turns over ${returned_nbr} disc(s)' ), array(
'player_id' => $activePlayerId,
'player_name' => $this->game->getPlayerNameById($activePlayerId),
'returned_nbr' => count( $turnedOverDiscs ),
'x' => $x,
'y' => $y
) );

$this->bga->notify->all( "turnOverDiscs", '', array(
'player_id' => $activePlayerId,
'turnedOver' => $turnedOverDiscs
) );
</pre>

Then we update the scores accordingly
<pre>
$playerIds = array_keys($this->game->loadPlayersBasicInfos());
foreach ($playerIds as $playerId) {
$tokens = $this->game->boardManager->countDiscsForPlayer((int) $playerId);
$this->bga->playerScore->set($playerId, $tokens); // this will update the JS counter automatically
}
</pre>

In BoardManager, add:
<pre>
public function countDiscsForPlayer(int $playerId): int
{
return (int) $this->game->getUniqueValueFromDB("SELECT COUNT(*) FROM `board` WHERE `board_player` = $playerId");
}
</pre>

We are using for that 2 notifications (<code>playDisc</code> and <code>turnOverDiscs</code> that we are going to implement on client side later). Note that the description of the <code>playDisc</code> notification will be logged in the game log.

Finally, we jump to the next game state.
<pre>
// Then, go to the next state
return NextPlayer::class;
</pre>

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

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

A last thing to do on the server side is to activate the next player when we enter the <code>NextPlayer</code> game state (in the <code>modules/php/States/NextPlayer.php</code> file):

Add `const ST_END_GAME = 99;` at the top of the file, then add:

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

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

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

// Can this player play?

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

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

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

[[File:reversi9.jpg]]

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

==Make the move appear automatically==

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

In our <code>setupNotifications</code> method in <code>modules/js/Game.js</code>, we tell BGA to listen to notifications we will add later (<code>playDisc</code> and <code>turnOverDiscs</code>) using promise-based notifications:

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

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

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

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

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

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

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

<pre>
async animateTurnOverDisc(disc, targetColor) {
const squareDiv = document.getElementById(`square_${disc.x}_${disc.y}`);
const discDiv = document.getElementById(`disc_${disc.x}_${disc.y}`);

squareDiv.classList.add('flip-animation');
await this.bga.gameui.wait(500); // for the flip animation to finish

discDiv.dataset.color = targetColor;

const parallelAnimations = [{
keyframes: [ // flip the disc
{ transform: `rotateY(180deg)` },
{ transform: `rotateY(0deg)` },
]
}, {
keyframes: [ // lift the disc
{ transform: `translate(0, -12px) scale(1.2)`, offset: 0.5 },
]
}];

await this.animationManager.slideAndAttach(discDiv, squareDiv, { duration: 1000, parallelAnimations });

squareDiv.classList.remove('flip-animation');
await this.bga.gameui.wait(500); // for the flip animation removal to finish
}

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

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

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

We create a chain of 3 animations using await to make the square highlight, then flip the token, then remove the square highlight.

==Implement the zombie mode ==
When a player leave the table, a Zombie (bot) will play for the leaver, so the table can continue. For that, we write code in the zombieTurn function.

to learn more about the Zombie mode, read [[Zombie Mode]]

Add this at the end of your PlayDisc.php file :
<pre>
function zombie(int $playerId) {
// Zombie level 1
$possibleMoves = $this->game->boardManager->getPossibleMoves($playerId);
// transform the 2 dimensional array into a flat array of possible [$x, $y]
$possibleMovesArray = [];
foreach($possibleMoves as $x => $ys) {
foreach($ys as $y => $valid) {
$possibleMovesArray[] = [$x, $y];
}
}

$zombieChoice = $this->getRandomZombieChoice($possibleMovesArray);
return $this->actPlayDisc($zombieChoice[0], $zombieChoice[1], $playerId);
}
</pre>

And that's it ! Everytime a leaver should be playing, the Zombie will random play one of the possible moves, and the remaining player will be able to play the next move.

== Add a debug function to help up test the code==
Add this at the end of your Game.php file :
<pre>

function debug_playAutomatically(int $moves = 50) {
$this->bga->debug->playUntil(fn(int $count) => $count === $moves);
}

function debug_playToEndGame() {
$this->debug_playAutomatically(64); // reversi max moves is under 64 for the standard size board
}
</pre>
This function plays automatically until we reach the end of the game. The functions starting with "debug_" can be triggered in the Studio with a special menu.
It uses the tool <code>$this->debug->playUntil</code> that will trigger zombie actions, but you could put any code in the debug function for the tests you need.

Start a new game, click on the Bug icon on the top left then "playToEndGame". You should see the game randomly playing until it reaches the end game, so it helps you check the animations, and you can see if the final scoring is also working as expected. This example will allow us to easily test the Zombie code, as it will play as a Zombie for all players until the end of the game. It's also an easy way to see if end score computation is working as expected!

You can create as many debug function as you like!

==Optional: add unit tests==
Follow the instruction on https://en.doc.boardgamearena.com/Testing_by_developer#PHP to setup phpunit and create the first Reversi unit tests that are given as examples there.

Running <code>phpunit</code>, it should be 4/4 OK! And we have a good hint the case of the full board should be handled OK without actually completing a game :)

==After the tutorial==
You might want to check another tutorial, or start working on your first real project !

[[Create a game in BGA Studio: Complete Walkthrough]]
[[Category:Studio]]

Tutorial reversi

2026-03-26T21:23:28Z

RichardSPeters: in the State Machine section remov confusion re PlayDisc and PlayerTurn

== Introduction ==

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

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

== Create your first game ==

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

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

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

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

== Editing the game information (Optional) ==

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

==== Edits to fix Errors ====
* Edit your local copy of the <code>gameinfos.inc.php</code> file:
** Change the <code>bgg_id</code> value from <code>0</code> to <code>2389</code> - that's around line 26.
** Add <code>1,</code> to the players array (so you can start 1-player games while testing) - that's around line 29.
* Upload the <code>gameinfos.inc.php</code> file to the SFTP server (see [[First_steps_with_BGA_Studio#Connect_to_your_SFTP_folder|Connect to your SFTP folder]]).

==== Test your Edits ====
* Go back to your project page, and in the the local version, click Game page and check if the information match what you changed in the gameinfos file. [[File:Studio local version block.png|frameless]]

===== Not working? =====
Some changes will require bypassing the cache (adding/changing images). It is often worth doing a hard refresh (Ctrl+F5) to make sure the latest version is used.

== Make sure the IDE is properly configured ==
Try to add some invalid values in the framework names like this :

[[File:Voluntary reversi tutorial ide error.png]]

The error should be underlined if your IDE is properly configured. If it is not, check [[Setting up BGA Development environment using VSCode]]

In the same fashion, the autocomplete of the IDE should propose you some values after <code>this->bga-></code>.

You can also check if the upload works as expected, the game should now work and display the error (Undefined property: Bga\Games\EmptyGame\Game::$bgaTEST ...).

Revert to the correct syntax.

== Make it look like Reversi ==

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

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

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

[[File:Board.jpg]]

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

==== Add the board ====
use lowercase file names
* upload <code>board.jpg</code> in your <code>img/</code> directory.
* edit <code>modules/js/Game.js</code> to add the <code>div</code> for your board at the beginning of the setup function.

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

Edit the Game.js file and replace the code after '''// Example to add a div on the game area''' with the following:
<pre>
this.bga.gameArea.getElement().insertAdjacentHTML('beforeend', `
<div id="board">
</div>
`);
</pre>

Note: example above use backticks, aka string template literals. This technique used a lot in code of games as it allows to easily create html with strings substitutions, use quotes, double quotes and newlines.
If you don't know what it is check here
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals

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

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

and remove the code in Game.js in method onEnteringState that refers to adding action buttons and remove the section under <code>// example of adding a div for each player"</code>.

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

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

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

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

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

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

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

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

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

.square {
width: 62px;
height: 62px;
position: absolute;
background-color: red;
display: flex;
justify-content: center;
align-items: center;
}
</pre>

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

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

[[File:reversi2.jpg]]

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

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

==The Tokens==

Now, our board is ready for some tokens!

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

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

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

[[File:tokens.png]]

Upload this image file <code>tokens.png</code> in your <code>img/</code> directory. NB: may need to manually upload as have found that the automatic SFTP does't seem to pick up images.

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

====Style the Tokens in .css file ====
<pre>
.disc {
position: relative;
width: 54px;
height: 54px;
z-index: 3;
transform-style: preserve-3d;
}
.disc .disc-faces {
transform-style: preserve-3d;
}
.disc[data-color="000000"] .disc-faces {
transform: rotateY(180deg);
}

.disc-face {
position: absolute;
width: 54px;
height: 54px;
background-image: url('img/tokens.png');
background-size: auto 100%;
backface-visibility: hidden;
}
.disc-face[data-side="white"] {
background-position-x: 0%;
transform: rotateY(0deg);
}
.disc-face[data-side="black"] {
background-position-x: 100%;
transform: rotateY(180deg);
}
</pre>

With this CSS code, we can set and change the token color by changing the <code>data-color</code> attribute. Using data instead of a class ensures it can be only one of them (the disc cannot be black and white at the same time).
We will create a disc-faces div in the disc containing 2 disc-face divs, to represent each face of the disc. It will allow us to have a nice flip animation!

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

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

<pre>
async addDiscOnBoard( x, y, playerId, animate = true )
{
const color = this.gamedatas.players[ playerId ].color;
const discId = `disc_${x}_${y}`;

document.getElementById(`square_${x}_${y}`).insertAdjacentHTML('beforeend', `
<div class="disc" data-color="${color}" id="${discId}">
<div class="disc-faces">
<div class="disc-face" data-side="white"></div>
<div class="disc-face" data-side="black"></div>
</div>
</div>
`);

if (animate) {
const element = document.getElementById(discId);
await this.animationManager.fadeIn(element, document.getElementById(`overall_player_board_${playerId}`));
}
}
</pre>

For this to work, you will also need to initialize the animation manager. Include the function in your .js file by updating as outlined here: [[BgaAnimations]]. Then add this in the setup function:
<pre>

this.animationManager = new BgaAnimations.Manager({
animationsActive: () => this.bga.gameui.bgaAnimationsActive(),
});
</pre>

=====Utility Method Explanation=====
*with <code>element.insertAdjacentHTML</code> method, we create a HTML piece of code and insert it as a new child of the square div element.
*Immediately after, using <code>this.animationManager.fadeIn</code> BGA method, we make the disc slide in (with a fade in animation) from the player panel.

Also note the trailing comma - this is needed because there may be other functions defined after this one, making <code>addDiscOnBoard</code> just one element in an array of functions.

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

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

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

===Test the Token===
Now, to test if everything works fine we will call the <code>addTokenOnBoard()</code> in .js file to Test

In <code>modules/js/Game.js</code>, in the <code>setup</code> function, under the code we added to generate the squares.
this.addDiscOnBoard(2, 2, this.bga.players.getCurrentPlayerId(), false);
Now restart the game.

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

[[File:reversi3.jpg]]

==The database==

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

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

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

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

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

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

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

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

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

Start a new game and verify a table is created : Click the "Go to game database", use the login and password your received by email, then you should see <code>board</code> in the list of tables (the db of the current table is automatically selected when clicking on this button).

== Setup the initial game position ==

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

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

===Initialize the Board in modules/php/Game.php file===
Under <code>// TODO: setup the initial game situation here</code>, initialize the board
<pre>
list( $blackplayer_id, $whiteplayer_id ) = array_keys( $players );
// Init the board
$this->boardManager->initializeBoard(8, (int) $blackplayer_id, (int) $whiteplayer_id);
</pre>

Wait, is that all?

No, the boardManager doesn't exist, we'll create it so it will handle all the functions related the tokens on the board. Splitting the code in multiple files will help us have easier to read classes, even more if each class handle a specific responsability.

Create a BoardManager.php file next to Game.php, and put this code in it:
<pre>
<?php
declare(strict_types=1);

namespace Bga\Games\Reversi;

class BoardManager
{
public function __construct(private Game $game)
{
}

public function initializeBoard(int $boardSize, int $blackPlayerId, int $whitePlayerId): void
{
$sqlValues = [];
$boardSizeHalf = (int) floor($boardSize / 2);

for ($x = 1; $x <= $boardSize; $x++) {
for ($y = 1; $y <= $boardSize; $y++) {
$discValue = 'NULL';
if (($x === $boardSizeHalf && $y === $boardSizeHalf) || ($x === ($boardSizeHalf + 1) && $y === ($boardSizeHalf + 1))) {
$discValue = (string) $whitePlayerId;
} elseif (($x === $boardSizeHalf && $y === ($boardSizeHalf + 1)) || ($x === ($boardSizeHalf + 1) && $y === $boardSizeHalf)) {
$discValue = (string) $blackPlayerId;
}

$sqlValues[] = "($x,$y,$discValue)";
}
}

$sql = "INSERT INTO `board` (`board_x`,`board_y`,`board_player`) VALUES " . implode(',', $sqlValues);
$this->game->DbQuery($sql);
}
}
</pre>

Once the php file is created edit the namespace and change \Reversi to be the name of your project

Note: the file name match the class name, and the namespace will now match the one from Game.php (so we are following PSR-4 specification), allowing BGA to autoload the class when we will need it. Let's initialize it from the Game.php file!

Before the Game __construct, add
<pre>
public BoardManager $boardManager;
</pre>

At the end of the Game __construct, add
<pre>
$this->boardManager = new BoardManager($this);
</pre>

Passing the game object to the constructor allows us to use its db functions.

If we were managing cards, we would have probably used the [[Deck]] component, and ideally we would create a CardManager that holds the Deck and all game specific logic about managing the cards.

==== Board Initialization Explanation ====

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

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

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

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

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

<pre>
// Get reversi board token
$result['board'] = $this->boardManager->getOccupiedDiscs();
</pre>
And in the board manager, add:
<pre>
public function getOccupiedDiscs(): array
{
return $this->game->getObjectListFromDB(
"SELECT `board_x` `x`, `board_y` `y`, `board_player` `player`
FROM `board`
WHERE `board_player` IS NOT NULL"
);
}
</pre>

Next, you will modify the query that gets player information to also get the player's colors. Above the lines you just inserted in <code>getAllDatas()</code> notice how we've added <code>player_color color</code> to the sql query in the code below.

<pre>
$result["players"] = $this->getCollectionFromDb(
"SELECT `player_id` `id`, `player_score` `score`, `player_color` `color` FROM `player`"
);
</pre>

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

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

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

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

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

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

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

[[File:reversi5.jpg]]

It starts to feel like Reversi here...

==State Machine==

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

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

[[File:reversi6.jpg]]

===Build your States===
And here are the classes we need to create on the <code>module/php/States</code> folder, according to this diagram:

'''PlayerTurn.php:'''
<pre>
<?php

declare(strict_types=1);

namespace Bga\Games\Reversi\States;

use Bga\GameFramework\StateType;
use Bga\Games\Reversi\Game;

class PlayerTurn extends \Bga\GameFramework\States\GameState
{
public function __construct(protected Game $game) {
parent::__construct($game,
id: 10,
type: StateType::ACTIVE_PLAYER,

description: clienttranslate('${actplayer} must play a disc'),
descriptionMyTurn: clienttranslate('${you} must play a disc'),
);
}

function zombie(int $playerId) {
}
}
</pre>

(The ''declare(strict_types=1)'' is optional but recommended for new games). The ''<?php'' at the beginning is necessary for your IDE to understand the php syntax. )

In PlayerTurn.js remove the code in onEnteringState (which sets the title top you/activealayer must play a counter

'''NextPlayer.php:'''
<pre>
<?php

declare(strict_types=1);

namespace Bga\Games\Reversi\States;

use Bga\GameFramework\StateType;
use Bga\Games\Reversi\Game;

class NextPlayer extends \Bga\GameFramework\States\GameState
{

public function __construct(protected Game $game) {
parent::__construct($game,
id: 90,
type: StateType::GAME,

updateGameProgression: true,
);
}
}
</pre>
Note: state ids 1 and 99 are reserved by the framework for gameSetup and gameEnd. We don't need to describe those states as the framework will take care of that for us.

In setupNewGame in Game.php, make sure the return is <code>return PlayerTurn::class;</code> so the framework knows which game state is the initial one.

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

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

[[File:reversi7.jpg]]

==The rules==

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

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

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

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

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

==Display allowed moves==

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

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

<pre>
function getArgs(int $activePlayerId): array
{
return [
'possibleMoves' => $this->game->boardManager->getPossibleMoves($activePlayerId)
];
}
</pre>

Now we need to handle it on the JS side.
Replace the state classes definition in the Game constructor by this:
<pre>
// Declare the State classes
this.playDisc = new PlayDisc(this, bga);
this.bga.states.register('PlayDisc', this.playDisc);
</pre>
So it matches the state we described in PHP. The state name is the PHP class name, that we use in register to link them.

Replace the class PlayerTurn in <code>modules/js/Game.js</code> by this one:
<pre>
class PlayDisc {
constructor(game, bga) {
this.game = game;
this.bga = bga;
}

onEnteringState(args, isCurrentPlayerActive) {
this.bga.statusBar.setTitle(isCurrentPlayerActive ?
_('${you} must play a disc') :
_('${actplayer} must play a disc')
);

if (isCurrentPlayerActive) {
this.updatePossibleMoves(args.possibleMoves);
}
}
}
</pre>

<b>Note:</b> We set the title when entering the state, so you can now remove description/descriptionMyTurn in the PHP class that was just here for test purpose.

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

Each time we enter into a new game state, we use the <code>onEnteringState</code> Javascript method of the JS State class. This lets us use the data returned by the method above on the client side.

So, when we enter into <code>PlayDisc</code> game state, we call our <code>updatePossibleMoves</code> method (under the "Utility methods" section). This method is added to PlayDisc class and looks like this:
<pre>
updatePossibleMoves(possibleMoves) {
// Remove current possible moves
document.querySelectorAll('.possibleMove').forEach(div => div.classList.remove('possibleMove'));

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

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

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

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

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

And here we are:

[[File:reversi8.jpg.jpg]]

==Let's play ==

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

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

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

Now, our "onPlayDisc" method is called each time someone clicks on a square.

Here's our "onPlayDisc" method below:

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

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

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

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

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

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

<pre>
#[PossibleAction]
function actPlayDisc( int $x, int $y, int $activePlayerId )
{
</pre>
And add <code>use Bga\GameFramework\States\PossibleAction;</code> at the top of the file.

(The function will be called when the front-side action is triggered using the Autowire mechanism, if you want to see how it works in details check [[Main game logic: Game.php|https://en.doc.boardgamearena.com/Main_game_logic:_Game.php#Actions_%28autowired%29]] )

now, we are using the <code>getTurnedOverDiscs</code> method again to check that this move is possible:
<pre>
// Now, check if this is a possible move
$board = $this->game->boardManager->getBoard();
$turnedOverDiscs = $this->game->getTurnedOverDiscs( $x, $y, $activePlayerId, $board );

if( count( $turnedOverDiscs ) === 0 ) {
throw new SystemException("Impossible move");
}
</pre>

we update the database to change the color of all turned over disc + the disc we just placed:
<pre>
// Let's place a disc at x,y and return all "$returned" discs to the active player

$this->game->boardManager->applyMove($activePlayerId, $x, $y, $turnedOverDiscs);
</pre>

We add this part to the BoardManager before going back to our act function:
<pre>
public function applyMove(int $playerId, int $x, int $y, array $turnedOverDiscs): void
{
$positions = [];
foreach ($turnedOverDiscs as $turnedOver) {
$turnedX = (int) $turnedOver['x'];
$turnedY = (int) $turnedOver['y'];
$positions[] = "($turnedX,$turnedY)";
}
$positions[] = "($x,$y)";

$sql = "UPDATE `board` SET `board_player` = $playerId WHERE (`board_x`, `board_y`) IN (" . implode(',', $positions) . ")";
$this->game->DbQuery($sql);
}
</pre>

we manage game statistics:
<pre>
$this->bga->playerStats->inc('turnedOver', $disc_count, $activePlayerId);
$updatedStat = 'discPlayedOnCenter';
if( ($x==1 && $y==1) || ($x==$board_size && $y==1) || ($x==1 && $y==$board_size) || ($x==$board_size && $y==$board_size) ) {
$updatedStat = 'discPlayedOnCorner';
} else if( $x==1 || $x==$board_size || $y==1 || $y==$board_size ) {
$updatedStat = 'discPlayedOnBorder';
}
$this->bga->playerStats->inc($updatedStat, 1, $activePlayerId);
</pre>

Notify the turned discs:
<pre>
// Notify
$this->bga->notify->all( "playDisc", clienttranslate( '${player_name} plays a disc and turns over ${returned_nbr} disc(s)' ), array(
'player_id' => $activePlayerId,
'player_name' => $this->game->getPlayerNameById($activePlayerId),
'returned_nbr' => count( $turnedOverDiscs ),
'x' => $x,
'y' => $y
) );

$this->bga->notify->all( "turnOverDiscs", '', array(
'player_id' => $activePlayerId,
'turnedOver' => $turnedOverDiscs
) );
</pre>

Then we update the scores accordingly
<pre>
$playerIds = array_keys($this->game->loadPlayersBasicInfos());
foreach ($playerIds as $playerId) {
$tokens = $this->game->boardManager->countDiscsForPlayer((int) $playerId);
$this->bga->playerScore->set($playerId, $tokens); // this will update the JS counter automatically
}
</pre>

In BoardManager, add:
<pre>
public function countDiscsForPlayer(int $playerId): int
{
return (int) $this->game->getUniqueValueFromDB("SELECT COUNT(*) FROM `board` WHERE `board_player` = $playerId");
}
</pre>

We are using for that 2 notifications (<code>playDisc</code> and <code>turnOverDiscs</code> that we are going to implement on client side later). Note that the description of the <code>playDisc</code> notification will be logged in the game log.

Finally, we jump to the next game state.
<pre>
// Then, go to the next state
return NextPlayer::class;
</pre>

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

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

A last thing to do on the server side is to activate the next player when we enter the <code>NextPlayer</code> game state (in the <code>modules/php/States/NextPlayer.php</code> file):

Add `const ST_END_GAME = 99;` at the top of the file, then add:

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

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

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

// Can this player play?

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

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

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

[[File:reversi9.jpg]]

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

==Make the move appear automatically==

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

In our <code>setupNotifications</code> method in <code>modules/js/Game.js</code>, we tell BGA to listen to notifications we will add later (<code>playDisc</code> and <code>turnOverDiscs</code>) using promise-based notifications:

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

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

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

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

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

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

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

<pre>
async animateTurnOverDisc(disc, targetColor) {
const squareDiv = document.getElementById(`square_${disc.x}_${disc.y}`);
const discDiv = document.getElementById(`disc_${disc.x}_${disc.y}`);

squareDiv.classList.add('flip-animation');
await this.bga.gameui.wait(500); // for the flip animation to finish

discDiv.dataset.color = targetColor;

const parallelAnimations = [{
keyframes: [ // flip the disc
{ transform: `rotateY(180deg)` },
{ transform: `rotateY(0deg)` },
]
}, {
keyframes: [ // lift the disc
{ transform: `translate(0, -12px) scale(1.2)`, offset: 0.5 },
]
}];

await this.animationManager.slideAndAttach(discDiv, squareDiv, { duration: 1000, parallelAnimations });

squareDiv.classList.remove('flip-animation');
await this.bga.gameui.wait(500); // for the flip animation removal to finish
}

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

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

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

We create a chain of 3 animations using await to make the square highlight, then flip the token, then remove the square highlight.

==Implement the zombie mode ==
When a player leave the table, a Zombie (bot) will play for the leaver, so the table can continue. For that, we write code in the zombieTurn function.

to learn more about the Zombie mode, read [[Zombie Mode]]

Add this at the end of your PlayDisc.php file :
<pre>
function zombie(int $playerId) {
// Zombie level 1
$possibleMoves = $this->game->boardManager->getPossibleMoves($playerId);
// transform the 2 dimensional array into a flat array of possible [$x, $y]
$possibleMovesArray = [];
foreach($possibleMoves as $x => $ys) {
foreach($ys as $y => $valid) {
$possibleMovesArray[] = [$x, $y];
}
}

$zombieChoice = $this->getRandomZombieChoice($possibleMovesArray);
return $this->actPlayDisc($zombieChoice[0], $zombieChoice[1], $playerId);
}
</pre>

And that's it ! Everytime a leaver should be playing, the Zombie will random play one of the possible moves, and the remaining player will be able to play the next move.

== Add a debug function to help up test the code==
Add this at the end of your Game.php file :
<pre>

function debug_playAutomatically(int $moves = 50) {
$this->bga->debug->playUntil(fn(int $count) => $count === $moves);
}

function debug_playToEndGame() {
$this->debug_playAutomatically(64); // reversi max moves is under 64 for the standard size board
}
</pre>
This function plays automatically until we reach the end of the game. The functions starting with "debug_" can be triggered in the Studio with a special menu.
It uses the tool <code>$this->debug->playUntil</code> that will trigger zombie actions, but you could put any code in the debug function for the tests you need.

Start a new game, click on the Bug icon on the top left then "playToEndGame". You should see the game randomly playing until it reaches the end game, so it helps you check the animations, and you can see if the final scoring is also working as expected. This example will allow us to easily test the Zombie code, as it will play as a Zombie for all players until the end of the game. It's also an easy way to see if end score computation is working as expected!

You can create as many debug function as you like!

==Optional: add unit tests==
Follow the instruction on https://en.doc.boardgamearena.com/Testing_by_developer#PHP to setup phpunit and create the first Reversi unit tests that are given as examples there.

Running <code>phpunit</code>, it should be 4/4 OK! And we have a good hint the case of the full board should be handled OK without actually completing a game :)

==After the tutorial==
You might want to check another tutorial, or start working on your first real project !

[[Create a game in BGA Studio: Complete Walkthrough]]
[[Category:Studio]]

Tutorial reversi

2026-03-23T23:19:51Z

RichardSPeters: Minor tweaks

== Introduction ==

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

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

== Create your first game ==

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

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

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

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

== Editing the game information (Optional) ==

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

==== Edits to fix Errors ====
* Edit your local copy of the <code>gameinfos.inc.php</code> file:
** Change the <code>bgg_id</code> value from <code>0</code> to <code>2389</code> - that's around line 26.
** Add <code>1,</code> to the players array (so you can start 1-player games while testing) - that's around line 29.
* Upload the <code>gameinfos.inc.php</code> file to the SFTP server (see [[First_steps_with_BGA_Studio#Connect_to_your_SFTP_folder|Connect to your SFTP folder]]).

==== Test your Edits ====
* Go back to your project page, and in the the local version, click Game page and check if the information match what you changed in the gameinfos file. [[File:Studio local version block.png|frameless]]

===== Not working? =====
Some changes will require bypassing the cache (adding/changing images). It is often worth doing a hard refresh (Ctrl+F5) to make sure the latest version is used.

== Make sure the IDE is properly configured ==
Try to add some invalid values in the framework names like this :

[[File:Voluntary reversi tutorial ide error.png]]

The error should be underlined if your IDE is properly configured. If it is not, check [[Setting up BGA Development environment using VSCode]]

In the same fashion, the autocomplete of the IDE should propose you some values after <code>this->bga-></code>.

You can also check if the upload works as expected, the game should now work and display the error (Undefined property: Bga\Games\EmptyGame\Game::$bgaTEST ...).

Revert to the correct syntax.

== Make it look like Reversi ==

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

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

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

[[File:Board.jpg]]

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

==== Add the board ====
use lowercase file names
* upload <code>board.jpg</code> in your <code>img/</code> directory.
* edit <code>modules/js/Game.js</code> to add the <code>div</code> for your board at the beginning of the setup function.

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

Edit the Game.js file and replace the code after '''// Example to add a div on the game area''' with the following:
<pre>
this.bga.gameArea.getElement().insertAdjacentHTML('beforeend', `
<div id="board">
</div>
`);
</pre>

Note: example above use backticks, aka string template literals. This technique used a lot in code of games as it allows to easily create html with strings substitutions, use quotes, double quotes and newlines.
If you don't know what it is check here
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals

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

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

and remove the code in Game.js in method onEnteringState that refers to adding action buttons and remove the section under <code>// example of adding a div for each player"</code>.

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

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

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

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

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

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

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

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

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

.square {
width: 62px;
height: 62px;
position: absolute;
background-color: red;
display: flex;
justify-content: center;
align-items: center;
}
</pre>

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

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

[[File:reversi2.jpg]]

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

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

==The Tokens==

Now, our board is ready for some tokens!

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

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

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

[[File:tokens.png]]

Upload this image file <code>tokens.png</code> in your <code>img/</code> directory. NB: may need to manually upload as have found that the automatic SFTP does't seem to pick up images.

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

====Style the Tokens in .css file ====
<pre>
.disc {
position: relative;
width: 54px;
height: 54px;
z-index: 3;
transform-style: preserve-3d;
}
.disc .disc-faces {
transform-style: preserve-3d;
}
.disc[data-color="000000"] .disc-faces {
transform: rotateY(180deg);
}

.disc-face {
position: absolute;
width: 54px;
height: 54px;
background-image: url('img/tokens.png');
background-size: auto 100%;
backface-visibility: hidden;
}
.disc-face[data-side="white"] {
background-position-x: 0%;
transform: rotateY(0deg);
}
.disc-face[data-side="black"] {
background-position-x: 100%;
transform: rotateY(180deg);
}
</pre>

With this CSS code, we can set and change the token color by changing the <code>data-color</code> attribute. Using data instead of a class ensures it can be only one of them (the disc cannot be black and white at the same time).
We will create a disc-faces div in the disc containing 2 disc-face divs, to represent each face of the disc. It will allow us to have a nice flip animation!

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

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

<pre>
async addDiscOnBoard( x, y, playerId, animate = true )
{
const color = this.gamedatas.players[ playerId ].color;
const discId = `disc_${x}_${y}`;

document.getElementById(`square_${x}_${y}`).insertAdjacentHTML('beforeend', `
<div class="disc" data-color="${color}" id="${discId}">
<div class="disc-faces">
<div class="disc-face" data-side="white"></div>
<div class="disc-face" data-side="black"></div>
</div>
</div>
`);

if (animate) {
const element = document.getElementById(discId);
await this.animationManager.fadeIn(element, document.getElementById(`overall_player_board_${playerId}`));
}
}
</pre>

For this to work, you will also need to initialize the animation manager. Include the function in your .js file by updating as outlined here: [[BgaAnimations]]. Then add this in the setup function:
<pre>

this.animationManager = new BgaAnimations.Manager({
animationsActive: () => this.bga.gameui.bgaAnimationsActive(),
});
</pre>

=====Utility Method Explanation=====
*with <code>element.insertAdjacentHTML</code> method, we create a HTML piece of code and insert it as a new child of the square div element.
*Immediately after, using <code>this.animationManager.fadeIn</code> BGA method, we make the disc slide in (with a fade in animation) from the player panel.

Also note the trailing comma - this is needed because there may be other functions defined after this one, making <code>addDiscOnBoard</code> just one element in an array of functions.

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

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

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

===Test the Token===
Now, to test if everything works fine we will call the <code>addTokenOnBoard()</code> in .js file to Test

In <code>modules/js/Game.js</code>, in the <code>setup</code> function, under the code we added to generate the squares.
this.addDiscOnBoard(2, 2, this.bga.players.getCurrentPlayerId(), false);
Now restart the game.

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

[[File:reversi3.jpg]]

==The database==

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

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

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

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

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

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

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

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

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

Start a new game and verify a table is created : Click the "Go to game database", use the login and password your received by email, then you should see <code>board</code> in the list of tables (the db of the current table is automatically selected when clicking on this button).

== Setup the initial game position ==

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

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

===Initialize the Board in modules/php/Game.php file===
Under <code>// TODO: setup the initial game situation here</code>, initialize the board
<pre>
list( $blackplayer_id, $whiteplayer_id ) = array_keys( $players );
// Init the board
$this->boardManager->initializeBoard(8, (int) $blackplayer_id, (int) $whiteplayer_id);
</pre>

Wait, is that all?

No, the boardManager doesn't exist, we'll create it so it will handle all the functions related the tokens on the board. Splitting the code in multiple files will help us have easier to read classes, even more if each class handle a specific responsability.

Create a BoardManager.php file next to Game.php, and put this code in it:
<pre>
<?php
declare(strict_types=1);

namespace Bga\Games\Reversi;

class BoardManager
{
public function __construct(private Game $game)
{
}

public function initializeBoard(int $boardSize, int $blackPlayerId, int $whitePlayerId): void
{
$sqlValues = [];
$boardSizeHalf = (int) floor($boardSize / 2);

for ($x = 1; $x <= $boardSize; $x++) {
for ($y = 1; $y <= $boardSize; $y++) {
$discValue = 'NULL';
if (($x === $boardSizeHalf && $y === $boardSizeHalf) || ($x === ($boardSizeHalf + 1) && $y === ($boardSizeHalf + 1))) {
$discValue = (string) $whitePlayerId;
} elseif (($x === $boardSizeHalf && $y === ($boardSizeHalf + 1)) || ($x === ($boardSizeHalf + 1) && $y === $boardSizeHalf)) {
$discValue = (string) $blackPlayerId;
}

$sqlValues[] = "($x,$y,$discValue)";
}
}

$sql = "INSERT INTO `board` (`board_x`,`board_y`,`board_player`) VALUES " . implode(',', $sqlValues);
$this->game->DbQuery($sql);
}
}
</pre>

Once the php file is created edit the namespace and change \Reversi to be the name of your project

Note: the file name match the class name, and the namespace will now match the one from Game.php (so we are following PSR-4 specification), allowing BGA to autoload the class when we will need it. Let's initialize it from the Game.php file!

Before the Game __construct, add
<pre>
public BoardManager $boardManager;
</pre>

At the end of the Game __construct, add
<pre>
$this->boardManager = new BoardManager($this);
</pre>

Passing the game object to the constructor allows us to use its db functions.

If we were managing cards, we would have probably used the [[Deck]] component, and ideally we would create a CardManager that holds the Deck and all game specific logic about managing the cards.

==== Board Initialization Explanation ====

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

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

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

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

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

<pre>
// Get reversi board token
$result['board'] = $this->boardManager->getOccupiedDiscs();
</pre>
And in the board manager, add:
<pre>
public function getOccupiedDiscs(): array
{
return $this->game->getObjectListFromDB(
"SELECT `board_x` `x`, `board_y` `y`, `board_player` `player`
FROM `board`
WHERE `board_player` IS NOT NULL"
);
}
</pre>

Next, you will modify the query that gets player information to also get the player's colors. Above the lines you just inserted in <code>getAllDatas()</code> notice how we've added <code>player_color color</code> to the sql query in the code below.

<pre>
$result["players"] = $this->getCollectionFromDb(
"SELECT `player_id` `id`, `player_score` `score`, `player_color` `color` FROM `player`"
);
</pre>

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

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

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

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

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

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

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

[[File:reversi5.jpg]]

It starts to feel like Reversi here...

==State Machine==

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

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

[[File:reversi6.jpg]]

===Build your States===
And here are the classes we need to create on the <code>module/php/States</code> folder, according to this diagram:

'''PlayDisc.php:'''
<pre>
<?php

declare(strict_types=1);

namespace Bga\Games\Reversi\States;

use Bga\GameFramework\StateType;
use Bga\Games\Reversi\Game;

class PlayDisc extends \Bga\GameFramework\States\GameState
{
public function __construct(protected Game $game) {
parent::__construct($game,
id: 10,
type: StateType::ACTIVE_PLAYER,

description: clienttranslate('${actplayer} must play a disc'),
descriptionMyTurn: clienttranslate('${you} must play a disc'),
);
}

function zombie(int $playerId) {
}
}
</pre>

(The ''declare(strict_types=1)'' is optional but recommended for new games). The ''<?php'' at the beginning is necessary for your IDE to understand the php syntax. )

'''NextPlayer.php:'''
<pre>
<?php

declare(strict_types=1);

namespace Bga\Games\Reversi\States;

use Bga\GameFramework\StateType;
use Bga\Games\Reversi\Game;

class NextPlayer extends \Bga\GameFramework\States\GameState
{

public function __construct(protected Game $game) {
parent::__construct($game,
id: 90,
type: StateType::GAME,

updateGameProgression: true,
);
}
}
</pre>
Note: state ids 1 and 99 are reserved by the framework for gameSetup and gameEnd. We don't need to describe those states as the framework will take care of that for us.

In setupNewGame, make sure the return is <code>return PlayerTurn::class;</code> so the framework knows which game state is the initial one.

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

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

[[File:reversi7.jpg]]

==The rules==

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

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

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

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

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

==Display allowed moves==

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

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

<pre>
function getArgs(int $activePlayerId): array
{
return [
'possibleMoves' => $this->game->boardManager->getPossibleMoves($activePlayerId)
];
}
</pre>

Now we need to handle it on the JS side.
Replace the state classes definition in the Game constructor by this:
<pre>
// Declare the State classes
this.playDisc = new PlayDisc(this, bga);
this.bga.states.register('PlayDisc', this.playDisc);
</pre>
So it matches the state we described in PHP. The state name is the PHP class name, that we use in register to link them.

Replace the class PlayerTurn in <code>modules/js/Game.js</code> by this one:
<pre>
class PlayDisc {
constructor(game, bga) {
this.game = game;
this.bga = bga;
}

onEnteringState(args, isCurrentPlayerActive) {
this.bga.statusBar.setTitle(isCurrentPlayerActive ?
_('${you} must play a disc') :
_('${actplayer} must play a disc')
);

if (isCurrentPlayerActive) {
this.updatePossibleMoves(args.possibleMoves);
}
}
}
</pre>

<b>Note:</b> We set the title when entering the state, so you can now remove description/descriptionMyTurn in the PHP class that was just here for test purpose.

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

Each time we enter into a new game state, we use the <code>onEnteringState</code> Javascript method of the JS State class. This lets us use the data returned by the method above on the client side.

So, when we enter into <code>PlayDisc</code> game state, we call our <code>updatePossibleMoves</code> method (under the "Utility methods" section). This method is added to PlayDisc class and looks like this:
<pre>
updatePossibleMoves(possibleMoves) {
// Remove current possible moves
document.querySelectorAll('.possibleMove').forEach(div => div.classList.remove('possibleMove'));

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

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

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

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

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

And here we are:

[[File:reversi8.jpg.jpg]]

==Let's play ==

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

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

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

Now, our "onPlayDisc" method is called each time someone clicks on a square.

Here's our "onPlayDisc" method below:

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

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

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

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

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

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

<pre>
#[PossibleAction]
function actPlayDisc( int $x, int $y, int $activePlayerId )
{
</pre>
And add <code>use Bga\GameFramework\States\PossibleAction;</code> at the top of the file.

(The function will be called when the front-side action is triggered using the Autowire mechanism, if you want to see how it works in details check [[Main game logic: Game.php|https://en.doc.boardgamearena.com/Main_game_logic:_Game.php#Actions_%28autowired%29]] )

now, we are using the <code>getTurnedOverDiscs</code> method again to check that this move is possible:
<pre>
// Now, check if this is a possible move
$board = $this->game->boardManager->getBoard();
$turnedOverDiscs = $this->game->getTurnedOverDiscs( $x, $y, $activePlayerId, $board );

if( count( $turnedOverDiscs ) === 0 ) {
throw new SystemException("Impossible move");
}
</pre>

we update the database to change the color of all turned over disc + the disc we just placed:
<pre>
// Let's place a disc at x,y and return all "$returned" discs to the active player

$this->game->boardManager->applyMove($activePlayerId, $x, $y, $turnedOverDiscs);
</pre>

We add this part to the BoardManager before going back to our act function:
<pre>
public function applyMove(int $playerId, int $x, int $y, array $turnedOverDiscs): void
{
$positions = [];
foreach ($turnedOverDiscs as $turnedOver) {
$turnedX = (int) $turnedOver['x'];
$turnedY = (int) $turnedOver['y'];
$positions[] = "($turnedX,$turnedY)";
}
$positions[] = "($x,$y)";

$sql = "UPDATE `board` SET `board_player` = $playerId WHERE (`board_x`, `board_y`) IN (" . implode(',', $positions) . ")";
$this->game->DbQuery($sql);
}
</pre>

we manage game statistics:
<pre>
$this->bga->playerStats->inc('turnedOver', $disc_count, $activePlayerId);
$updatedStat = 'discPlayedOnCenter';
if( ($x==1 && $y==1) || ($x==$board_size && $y==1) || ($x==1 && $y==$board_size) || ($x==$board_size && $y==$board_size) ) {
$updatedStat = 'discPlayedOnCorner';
} else if( $x==1 || $x==$board_size || $y==1 || $y==$board_size ) {
$updatedStat = 'discPlayedOnBorder';
}
$this->bga->playerStats->inc($updatedStat, 1, $activePlayerId);
</pre>

Notify the turned discs:
<pre>
// Notify
$this->bga->notify->all( "playDisc", clienttranslate( '${player_name} plays a disc and turns over ${returned_nbr} disc(s)' ), array(
'player_id' => $activePlayerId,
'player_name' => $this->game->getPlayerNameById($activePlayerId),
'returned_nbr' => count( $turnedOverDiscs ),
'x' => $x,
'y' => $y
) );

$this->bga->notify->all( "turnOverDiscs", '', array(
'player_id' => $activePlayerId,
'turnedOver' => $turnedOverDiscs
) );
</pre>

Then we update the scores accordingly
<pre>
$playerIds = array_keys($this->game->loadPlayersBasicInfos());
foreach ($playerIds as $playerId) {
$tokens = $this->game->boardManager->countDiscsForPlayer((int) $playerId);
$this->bga->playerScore->set($playerId, $tokens); // this will update the JS counter automatically
}
</pre>

In BoardManager, add:
<pre>
public function countDiscsForPlayer(int $playerId): int
{
return (int) $this->game->getUniqueValueFromDB("SELECT COUNT(*) FROM `board` WHERE `board_player` = $playerId");
}
</pre>

We are using for that 2 notifications (<code>playDisc</code> and <code>turnOverDiscs</code> that we are going to implement on client side later). Note that the description of the <code>playDisc</code> notification will be logged in the game log.

Finally, we jump to the next game state.
<pre>
// Then, go to the next state
return NextPlayer::class;
</pre>

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

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

A last thing to do on the server side is to activate the next player when we enter the <code>NextPlayer</code> game state (in the <code>modules/php/States/NextPlayer.php</code> file):

Add `const ST_END_GAME = 99;` at the top of the file, then add:

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

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

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

// Can this player play?

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

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

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

[[File:reversi9.jpg]]

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

==Make the move appear automatically==

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

In our <code>setupNotifications</code> method in <code>modules/js/Game.js</code>, we tell BGA to listen to notifications we will add later (<code>playDisc</code> and <code>turnOverDiscs</code>) using promise-based notifications:

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

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

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

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

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

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

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

<pre>
async animateTurnOverDisc(disc, targetColor) {
const squareDiv = document.getElementById(`square_${disc.x}_${disc.y}`);
const discDiv = document.getElementById(`disc_${disc.x}_${disc.y}`);

squareDiv.classList.add('flip-animation');
await this.bga.gameui.wait(500); // for the flip animation to finish

discDiv.dataset.color = targetColor;

const parallelAnimations = [{
keyframes: [ // flip the disc
{ transform: `rotateY(180deg)` },
{ transform: `rotateY(0deg)` },
]
}, {
keyframes: [ // lift the disc
{ transform: `translate(0, -12px) scale(1.2)`, offset: 0.5 },
]
}];

await this.animationManager.slideAndAttach(discDiv, squareDiv, { duration: 1000, parallelAnimations });

squareDiv.classList.remove('flip-animation');
await this.bga.gameui.wait(500); // for the flip animation removal to finish
}

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

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

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

We create a chain of 3 animations using await to make the square highlight, then flip the token, then remove the square highlight.

==Implement the zombie mode ==
When a player leave the table, a Zombie (bot) will play for the leaver, so the table can continue. For that, we write code in the zombieTurn function.

to learn more about the Zombie mode, read [[Zombie Mode]]

Add this at the end of your PlayDisc.php file :
<pre>
function zombie(int $playerId) {
// Zombie level 1
$possibleMoves = $this->game->boardManager->getPossibleMoves($playerId);
// transform the 2 dimensional array into a flat array of possible [$x, $y]
$possibleMovesArray = [];
foreach($possibleMoves as $x => $ys) {
foreach($ys as $y => $valid) {
$possibleMovesArray[] = [$x, $y];
}
}

$zombieChoice = $this->getRandomZombieChoice($possibleMovesArray);
return $this->actPlayDisc($zombieChoice[0], $zombieChoice[1], $playerId);
}
</pre>

And that's it ! Everytime a leaver should be playing, the Zombie will random play one of the possible moves, and the remaining player will be able to play the next move.

== Add a debug function to help up test the code==
Add this at the end of your Game.php file :
<pre>

function debug_playAutomatically(int $moves = 50) {
$this->bga->debug->playUntil(fn(int $count) => $count === $moves);
}

function debug_playToEndGame() {
$this->debug_playAutomatically(64); // reversi max moves is under 64 for the standard size board
}
</pre>
This function plays automatically until we reach the end of the game. The functions starting with "debug_" can be triggered in the Studio with a special menu.
It uses the tool <code>$this->debug->playUntil</code> that will trigger zombie actions, but you could put any code in the debug function for the tests you need.

Start a new game, click on the Bug icon on the top left then "playToEndGame". You should see the game randomly playing until it reaches the end game, so it helps you check the animations, and you can see if the final scoring is also working as expected. This example will allow us to easily test the Zombie code, as it will play as a Zombie for all players until the end of the game. It's also an easy way to see if end score computation is working as expected!

You can create as many debug function as you like!

==Optional: add unit tests==
Follow the instruction on https://en.doc.boardgamearena.com/Testing_by_developer#PHP to setup phpunit and create the first Reversi unit tests that are given as examples there.

Running <code>phpunit</code>, it should be 4/4 OK! And we have a good hint the case of the full board should be handled OK without actually completing a game :)

==After the tutorial==
You might want to check another tutorial, or start working on your first real project !

[[Create a game in BGA Studio: Complete Walkthrough]]
[[Category:Studio]]

Tutorial hearts

2026-03-23T21:06:10Z

RichardSPeters: small tweaks to sample code to bring it in line with current framework

{{Studio_Framework_Navigation}}

== Introduction ==

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

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

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

== Hearts Rules ==

Hearts is a trick-taking card game for four players where the goal is to score the fewest points.
Players aim to avoid taking tricks with heart cards (1 point each) and the Queen of Spades (13 points).
Each round, 13 cards are dealt, players pass three cards, and the player with the 2 of Clubs starts the first trick.
Play continues clockwise, with players needing to follow suit if they can, and the highest card of the lead suit wins the trick.
Hearts cannot be played until they are "broken" by a player who can't follow suit and discards a heart, or by a player leading with a heart after they've been broken.

== Create your first game ==

If you have not already, you have to create a project in BGA Studio. For this tutorial you can create a project heartsYOURNAME where
YOURNAME is your developer login name (or shorter version of thereof). You can also re-use the project you have created for the "First Steps" tutorial above.

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

With the initial skeleton of code provided, you can already start a game from the BGA Studio.

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

2. Modify the text in .js file (for example replace "Player zone content goes here" to "Hello"), reload the page in the browser and make sure your ftp sync works as expected.
Note: if you have not setup auto-sync do it now, manually copying files is a no-starter.

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

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

== Hook version control system ==

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

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

Different revisions represent different steps along the process, starting from original template to a PARTIAL game.

Note: the game was re-written using new template, the old code is in "oldframework" branch. The new template is in main branch.

The real hearts game (that you can play on BGA) can be found in your FTP home folder, after getting read-only access, go to https://studio.boardgamearena.com/projects, select Already Published and find Hearts to get access
(It may not match this tutorial as framework diverged since this game was created and it may not have been updated)

== Update game infos and box graphics ==

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

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

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

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

// Game publisher
'publisher' => 'Public Domain',

// Board Game Geek ID of the publisher
'publisher_bgg_id' => 171,

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

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

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

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

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

== Layout and Graphics ==

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

First copy a sprite with cards image from [https://x.boardgamearena.net/data/others/cards/FULLREZ_CARDS_ORIGINAL_NORMAL.jpg] into img/cards.jpg folder of your project.

Details about images can be found here: [[Game art: img directory]]. If you did not setup auto-sync of files, sync the graphics manually with remote folder (re-sync with your workspace).

Edit .js to add some divs to represent player table and hand area, at the beginning of the setup function

<pre>

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

this.bga.gameArea.getElement().insertAdjacentHTML(
"beforeend",
`
<div id="myhand_wrap" class="whiteblock">
<b id="myhand_label">${_("My hand")}</b>
<div id="myhand">
</div>
</div>

`,
);
// ...
</pre>

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

[[File:Heartsla-tpl2.png]]

Now lets add a card into the hand, just so you can feel it. Edit the html snippet we inserted earlier buy adding a line representing a card
<pre>
...
<div id="myhand">
<div class="fakecard"></div>
</div>
...
</pre>

Edit .css file, add this code (.css file is empty now, only has comments, just tuck this at the end)
<pre>
.fakecard {
display: inline-block;
position: relative;
margin-top: 5px;
border-radius: 5%;
width: 100px;
height: 135px;
background-size: calc(100px * 15);
background-image: url('img/cards.jpg'); /* temp hack to see it */
}
</pre>

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

You should see this (more less):

[[File:Heartsla-tpl3.png]]

Note: If you don't see the card a) check it was synced to remote folder b) force reload page

Awesome! Now lets do the rest of layout.

Let's complete the game template. You template should have this code, just leave it there
<pre>

// Example to add a div on the game area
this.bga.gameArea.getElement().insertAdjacentHTML("beforeend",
<div id="player-tables"></div>
`
);
</pre>

Then change the code following comment "// Setting up player boards" with this
<pre>
// Setting up player boards
const numPlayers = Object.keys(gamedatas.players).length;
Object.values(gamedatas.players).forEach((player, index) => {
document.getElementById("player-tables").insertAdjacentHTML(
"beforeend",
// we generate this html snippet for each player
`
<div class="playertable whiteblock playertable_${DIRECTIONS[index]}">
<div class="playertablename" style="color:#${player.color};">${player.name}</div>
<div id="tableau_${player.id}"></div>
</div>
`
);
});
</pre>
What we did is we added a template for every players at the table.
Now try to reload you game.
Oops! it won't load. This is to teach you how it will look like when you have syntax error in your js file. The game will hang loading at 10% or so. How to know what happened?
Open dev tools in browser (usually F12) and navigate to Console tab. You will see a stack trace of where error is. In our case
HeartsFIXME.js:68 Uncaught (in promise) ReferenceError: DIRECTIONS is not defined

In real hearts game they use this direction array to map every player to direction (like North) but its not needed, we can just use player index.
Lets just replace DIRECTIONS[index] with index, i.e
<div class="playertable whiteblock playertable_${index}">

Now delete the following section as we won't be using it<pre>
// Add test action buttons in the action status bar, simulating a card click:
playableCardsIds.forEach((cardId) =>
this.bga.statusBar.addActionButton(
_("Play card with id ${card_id}").replace("${card_id}", cardId),
() => this.onCardClick(cardId),
),
);

this.bga.statusBar.addActionButton(
_("Pass"),
() => this.bga.actions.performAction("actPass"),
{ color: "secondary" },
);

</pre>

Reload. If everything went well you should see this:

[[File:Heartsla-tpl4.png|alt=Display player space of all players]]

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

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

<pre>
:root {
--h-card-width: 100px;
--h-card-height: 135px;
--h-tableau-width: 220px;
--h-tableau-height: 180px;
}

#player-tables {
position: relative;
width: calc(var(--h-tableau-width) * 3.9);
height: calc(var(--h-tableau-height) * 2.4);
}

.playertablename {
font-weight: bold;
}

.playertable {
position: absolute;
text-align: center;
width: var(--h-tableau-width);
height: var(--h-tableau-height);
}

.playertable_0 {
top: 0px;
left: 50%;
margin-left: calc(var(--h-tableau-width) / 2 * -1);
}

.playertable_1 {
left: 0px;
top: 50%;
margin-top: calc(var(--h-tableau-height) / 2 * -1);
}
.playertable_2 {
right: 0px;
top: 50%;
margin-top: calc(var(--h-tableau-height) / 2 * -1);
}
.playertable_3 {
bottom: 0px;
left: 50%;
margin-left: calc(var(--h-tableau-width) / 2 * -1);
}
</pre>

and delete the following section from game.js as we won't be using it<pre>
// example of adding a div for each player
document.getElementById("player-tables").insertAdjacentHTML(
"beforeend",
`
<div id="player-table-${player.id}">
<strong>${player.name}</strong>
<div>Player zone content goes here</div>
</div>
`,
);

</pre>

Now you force Reload and you should see this:

[[File:Heartsla-tpl5.png]]

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

Here is some explanations about CSS (if you know everything about css already skip this):
* At top we defined some variables for sizes of cards and player "mats" (which we call tableau)
* We trying to layout mats in kind of diamond shape
* We define positions of our elements using top/bottom/left/right style property
* We used standard technique of centering the element which is use 50% for lets say "left", and then shift by half of size of object to actually center it (margin-left). You can remove margins to see how it look if we did not do that

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

== Game Interface with BGA Cards ==

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

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

First, we need to add dependencies in the Game.js file:
<pre>
const BgaAnimations = await importEsmLib('bga-animations', '1.x');
const BgaCards = await importEsmLib('bga-cards', '1.x');
</pre>

Now we will remove the fake card we added (in Game.js file) search and remove: <pre>
<div id="myhand">
<div class="fakecard"></div>
</div>
</pre>

Then we will add initialization code of bga cards and related component in setup method after the template code (i.e. where we defined the myhand div as this div is referenced by the following code) and before setupNotifications <pre>
// create the animation manager, and bind it to the `game.bgaAnimationsActive()` function
this.animationManager = new BgaAnimations.Manager({
animationsActive: () => this.bga.gameui.bgaAnimationsActive(),
});

const cardWidth = 100;
const cardHeight = 135;

// create the card manager
this.cardsManager = new BgaCards.Manager({
animationManager: this.animationManager,
type: "ha-card", // the "type" of our cards in css
getId: (card) => card.id,

cardWidth: cardWidth,
cardHeight: cardHeight,
cardBorderRadius: "5%",
setupFrontDiv: (card, div) => {
div.dataset.type = card.type; // suit 1..4
div.dataset.typeArg = card.type_arg; // value 2..14
div.style.backgroundPositionX = `calc(100% / 14 * (${card.type_arg} - 2))`; // 14 is number of columns in stock image minus 1
div.style.backgroundPositionY = `calc(100% / 3 * (${card.type} - 1))`; // 3 is number of rows in stock image minus 1
this.bga.gameui.addTooltipHtml(div.id, `tooltip of ${card.type}`);
},
});

// create the stock, in the game setup
this.handStock = new BgaCards.HandStock(
this.cardsManager,
document.getElementById("myhand")
);
// TODO: fix handStock
this.handStock.addCards([
{ id: 1, type: 2, type_arg: 4 }, // 4 of hearts
{ id: 2, type: 3, type_arg: 11 }, // Jack of clubs
]);
</pre>

Also we need to add this .css (anywhere), that will map front face of the card to our image (1500% is because this image 15 times bigger than single card on X axis)
<pre>
.ha-card-front {
background-size: 1500% auto;
background-image: url("img/cards.jpg");
}
</pre>

Explanations:
* First we created animation manager which will be used later
* Then we define constant with width and height of our cards in pixes
* Then we create the cards manager. We tell it how to get unique id of each card (getId), and how to setup the div representing the front of the card (setupFrontDiv). In this function we set data attributes for type and type_arg which we will use later, and we set background position to show correct part of sprite image.
* Then we create a hand stock component which will represent player's hand. It is attached to div with id "myhand".
* Finally we add two cards into the hand stock just for testing.

Now if you reload you should see two cards in your hand:

[[File:Heartsla-tpl6.png|alt=Display two cards in player's hand]]

Now we will add the "stock" object that will control player tableau (add in setup function before setupNotification)
<code>

// map stocks

this.tableauStocks = [];
Object.values(gamedatas.players).forEach((player, index) => {
// add player tableau stock
this.tableauStocks[player.id] = new BgaCards.LineStock(
this.cardsManager,
document.getElementById(`tableau_${player.id}`)
);

// TODO: fix tableauStocks
this.tableauStocks[player.id].addCards([
{ id: index + 10, type: index + 1, type_arg: index + 2 },
]);
});

</code>

[[File:Heartsla-tpl7.png]]

Explanations:
* We go over each player and create component called LineStock to represent player tableau, it will hold a single card
* We assign this into tableauStocks map indexed by player id to use later
* Finally we add a fake card into that stock just to see something

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

Let's hook it up. Add this in the setup method in .js file, before // TODO: fix handStock:

this.handStock.setSelectionMode("single");
this.handStock.onCardClick = (card) => {
alert("boom!");
};

Reload the game and click on one of the two Cards in your hand. You should get "boom".

We will stop for now with client because we need to code some server stuff.

== Game Database and Game Initialization ==

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

==== Database Schema ====
When you develop a game you need to figure out how you store your game pieces in database. This should be maximum 2 tables (like one for cards, items, tokens and meeples and one for counters).
In this game we will be using two tables, the default Deck table (supported by Deck component) and default "state variables" tables which called globals, to store some of integers.
In you never dealt with web servers - the database stores all information about your game and your php (server) code does not exists in memory between users actions.

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

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

This is how we map the database to our game:
* card_id: unique id of each card, it will be auto-generated
* card_type: it will be suite of the card 1 to 4 (Spades,Hearts,Clubs,Diamonds).
* card_type_arg: will be "value" of the card, 2 to 14 (2 is 2,...,10 is 10, 11 is Jack, ...)
* card_location: will be location of the card, like "deck", "hand", "tableau" etc
* card_location_arg: will be additional argument for location - the player id if card is in player's hand or tableau.

=== Game State Variables ===
<pre>
CREATE TABLE IF NOT EXISTS `card` (
`card_id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`card_type` varchar(16) NOT NULL,
`card_type_arg` int(11) NOT NULL,
`card_location` varchar(16) NOT NULL,
`card_location_arg` int(11) NOT NULL,
PRIMARY KEY (`card_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>Next we finally get into Game.php class (in modules/php subdir), where the main logic and db interaction would be. Find php constructor which should be
function __construct( )
This is first function in a file. Add this code to constructor (replace existing initGameStateLabel if any).
<pre>
public function __construct()
{
parent::__construct();
$this->initGameStateLabels(
[
"trick_color" => 11,
]
);

$this->cards = $this->deckFactory->createDeck('card'); // card is the our database name
// ...
</pre>

If you see errors in IDE its because we also have to declared "cards" as class member, add ''public Deck $cards;'' before the contructor.
Also if you using IDE it will suggest to import Deck class, accept it. If you are using 'vi' just add this import where other imports (use in php) at the begging of the file after namespace declaration.

use Bga\GameFramework\Components\Deck;

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

The variables are:

*"trick_color": numbers from 1 to 4 that map to card suit (not sure why it's called color; maybe it's a translation from French);

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

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

Note: if you have some other leftovers from template like playerEnergy, leave it for now as is.

Since we changed the database schema, we cannot re-use our existing game, we have to do express stop (from burger menu).

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

If you game won't even load and you want to stop it:
https://en.doc.boardgamearena.com/Tools_and_tips_of_BGA_Studio#Stopping_Hanging_Game

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

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

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

</pre>

Here we initialize all the globals to 0.

Next is to create our cards in the database. We have one deck of cards so it's pretty simple.
Insert this after // TODO: Setup the initial game situation here.

<pre>
// Create cards
$cards = [];
foreach ($this->card_types["suites"] as $suit => $suit_info) {
// spade, heart, diamond, club
foreach ($this->card_types["types"] as $value => $info_value) {
// 2, 3, 4, ... K, A
$cards[] = ['type' => $suit, 'type_arg' => $value, 'nbr' => 1];
}
}
$this->cards->createCards($cards, 'deck');
</pre>

This code that will create one of each card. But don't run it yet, because we missing ''card_types''.
So we have state of the game in the database, but there is some static game information which never changes.
This information should be stored in .php and this way it can be accessed from all .php files (and .js if you send it via getAllDatas()).

Note: originally it was stored in material.inc.php file which is no longer part of default template, when you have a lot of material it makes sence to get it out of Game.php

We will edit Game.php now by adding these lines in constructor (and replacing ''self::$CARD_TYPES'')

<pre>
$this->card_types = [
"suites" => [
1 => [
'name' => clienttranslate('Spade'),
],
2 => [
'name' => clienttranslate('Heart'),
],
3 => [
'name' => clienttranslate('Club'),
],
4 => [
'name' => clienttranslate('Diamond'),
]
],
"types" => [
2 => ['name' => '2'],
3 => ['name' => '3'],
4 => ['name' => '4'],
5 => ['name' => '5'],
6 => ['name' => '6'],
7 => ['name' => '7'],
8 => ['name' => '8'],
9 => ['name' => '9'],
10 => ['name' => '10'],
11 => ['name' => clienttranslate('J')],
12 => ['name' => clienttranslate('Q')],
13 => ['name' => clienttranslate('K')],
14 => ['name' => clienttranslate('A')]
]
];

</pre>

If you pass a value to the client via notification you should always use untranslated strings, and the client will translate it. Function 'clienttranslate' marks the value for translation but does not actually change it for php. For more about this wonderful translation stuff see [[Translations]].

Can also have declared this in the class (replace $CARD_TYPES)
public array $card_types;

Reload to make it still works (no errors).

==== Dealing Cards ====
After we have initialized our deck, we want to deal 13 at random for each player. Add this after createCards in setupNewGame function in the Game.php file:
<pre>
// Shuffle deck
$this->cards->shuffle('deck');
// Deal 13 cards to each players
$players = $this->loadPlayersBasicInfos();
foreach ($players as $player_id => $player) {
$this->cards->pickCards(13, 'deck', $player_id);
}

</pre>
In the next section we are going to learn how to show those cards to the right players, without exposing other player hands.

==Full Game Model Synchronization==

Now at any point in the game we need to make sure that database information can be reflected back in the UI, so we must fix the '''getAllDatas''' function
to return all possible data we need to reconstruct the game. This is in the Game.php file.

=== Player's Hand ===
The template for getAllDatas() already takes care of player info. Let's just
add hand and tableau data before we return a result.

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

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

Now on the client side we should display this data, so in your game.js file in the setup function (which is the receiver of getAllDatas), find // TODO: fix handStock
and replace our hack of putting cards directly into the hand with:

<pre>
// Cards in player's hand
this.handStock.addCards(Array.from(Object.values(this.gamedatas.hand)));

</pre>
So we added all cards from server to the hand stock. Have to do this ugly array convertion, hopefully they will fix addCards so we don't need to do this.

At this point, you have to RESTART a game and each player should see their hand!

At any point if code does not work on clinet side, add command "debugger;" in the code. In browser press F12 to get dev tools, then reload.
You will hit breakpoint and can you in browser debugger. Don't forget to remove debugger; code after.

=== Cards on Table ===
Now lets fix out tableau, find comment in setup method of .js file // TODO: fix tableau
and remove stock.addCards... from that loop. But right after this add
// Cards played on table
for (i in this.gamedatas.cardsontable) {
var card = this.gamedatas.cardsontable[i];
var player_id = card.location_arg;
this.tableauStocks[player_id].addCards([card]);
}

If you reload now you can see nothing on the table.

Next, we will hook-up clicking on card and test if our animation.

Find the "boom" we put in the click handler. Replace with this
this.handStock.onCardClick = (card) => {
this.tableauStocks[card.location_arg].addCards([card]);
};

Now if you reload you should be able to click on card from your hand and see it moving,
you can click on few cards this way. When you done enjoying the animation, press F5 to get your hand back.

[[File:Heartsla-sync.png]]

==State Machine==

Stop the game. We are about to work on the game logic.

You already read [http://www.slideshare.net/boardgamearena/bga-studio-focus-on-bga-game-state-machine Focus on BGA game state machine], so you know that this is the heart of your game logic.
Note: ignore all the source snippets in this presentation, as framework changed, just note the concepts.

Here are the states we need to build (excluding two more states we will add later to handle the exchange of cards at the beginning of the rounds):

*Cards are dealt to all players (lets call it "NewHand")
*Player start or respond to played card ("PlayerTurn")
*Game control is passed to next player or trick is ended ("NextPlayer")
*End of hand processing (scoring and check for end of game) ("EndHand")

Note: if you find states.inc.php file in top level directory - delete it now.

=== State Templates ===
We will create just barebones state files first:

==== States/NewHand.php ====
Let's create our first state - "NewHand". Create a new file under "module/php/States" and name it "'''NewHand.php'''".
<pre>

<?php
declare(strict_types=1);
namespace Bga\Games\HeartsFIXME\States;

use Bga\Games\HeartsFIXME\Game;
use Bga\GameFramework\StateType;
use Bga\GameFramework\States\GameState;

class NewHand extends GameState
{
public function __construct(protected Game $game)
{
parent::__construct(
$game,
id: 2, // the idea of the state
type: StateType::GAME, // This type means that no player is active, and the game will automatically progress
updateGameProgression: true, // entering this state can update the progress bar of the game
);
}

// The action we do when entering the state
public function onEnteringState()
{
return PlayerTurn::class;
}
}

</pre>
You can read more about it here: [[State classes: State directory]]

If you use IDE you see few errors:
* First there is no Bga\Games\HeartsFIXME\Game - that is because you games is not called HeartsFIXME, is something like HeartsFooBar - so you change this and namespace to your game name.
* Second it will compain abot NewTrick class - it does not exist yet

Let's implement the other states:

==== States/PlayerTurn.php ====
If file exists replace its content.
This action is different because it has an action a player must take. Read the comments in the code below to understand the syntax:
<pre>
<?php

declare(strict_types=1);

namespace Bga\Games\HeartsFIXME\States;

use Bga\Games\HeartsFIXME\Game;
use Bga\GameFramework\StateType;
use Bga\GameFramework\States\PossibleAction;
use Bga\GameFramework\States\GameState;
use Bga\GameFramework\UserException;

class PlayerTurn extends GameState
{
public function __construct(protected Game $game)
{
parent::__construct(
$game,
id: 31,
type: StateType::ACTIVE_PLAYER, // This state type means that one player is active and can do actions
description: clienttranslate('${actplayer} must play a card'), // We tell OTHER players what they are waiting for
descriptionMyTurn: clienttranslate('${you} must play a card'), // We tell the ACTIVE player what they must do
// We suround the code with clienttranslate() so that the text is sent to the client for translation (this will enable the game to support other languages)
);
}

#[PossibleAction] // a PHP attribute that tells BGA "this method describes a possible action that the player could take", so that you can call that action from the front (the client)
public function actPlayCard(int $cardId, int $activePlayerId)
{
// TODO: implement logic
return NextPlayer::class; // after the action, we move to the next player
}

public function zombie(int $playerId)
{
// We must implement this so BGA can auto play in the case a player becomes a zombie, but for this tutorial we won't handle this case
throw new UserException('Not implemented: zombie for player ${player_id}');
}
}

</pre>
You would also notice the "zombie" method. This would allow BGA to auto-player for the player if they became inactive. This is mandatory, but we will implement this later.

==== States/NextPlayer.php ====
This state have a couple of different options for what would be the next state:

* If not all players played a card in the current trick - we need to go to '''PlayerTurn''' (for the next player)
* If all players finished the trick but still have cards in their hand - we need to go to '''PlayerTurn'''
* If this is the last trick (no more cards in end) and it's finished, we need to go to '''EndHand'''

We will implement this logic later. For now let's return '''NewHandPlayerTurn''' (see onEnteringState).
<pre>
<?php
declare(strict_types=1);
namespace Bga\Games\HeartsFIXME\States;

use Bga\GameFramework\StateType;
use Bga\Games\HeartsFIXME\Game;
use Bga\GameFramework\States\GameState;

class NextPlayer extends GameState
{
public function __construct(protected Game $game)
{
parent::__construct(
$game,
id: 32,
type: StateType::GAME,
);
}

public function onEnteringState()
{
return PlayerTurn::class;
}
}

</pre>

==== States/EndHand.php ====
Here too we will have two options for transition, either we play another hand ('''NewHand''') or we finish the game (a reserved id for finishing the game is '''99''').

We will implement this logic later. For now let's return '''NewHand''' (see onEnteringState).

<pre>
<?php
declare(strict_types=1);
namespace Bga\Games\HeartsFIXME\States;

use Bga\GameFramework\StateType;
use Bga\Games\HeartsFIXME\Game;
use Bga\GameFramework\States\GameState;

class EndHand extends GameState
{
public function __construct(protected Game $game)
{
parent::__construct(
$game,
id: 40,
type: StateType::GAME,
description: "",
);
}

public function onEnteringState()
{
// TODO: implement logic
return NewHand::class;
}
}

</pre>

Check again that no HeartsFIXME left in the code, if yes replace with game name.

Remove EndScore.php - don't need it.

Don't start the game yet, it won't load, we have to clean up bunch of template code in the .js

=== Test Your Game is not broken ===
We changed state related logic, so we need to restart the game. If the game starts without error we are good. We won't be able to test the interactions yet because we need to implement the client side.

Think the following is from the old framework and no longer relevant.

<s>Since we added bunch of different states we need to remove some more templace code, in .js file find onUpdateActionButtons, and remove all functional code, leaving just this</s><pre>
onUpdateActionButtons: function (stateName, args) {
console.log("onUpdateActionButtons: " + stateName, args);

if (this.isCurrentPlayerActive()) {
switch (stateName) {
case "playerTurn":
break;
}
}
},
</pre>

=== State Logic ===
Now if you RESTART the game, it should not crash and you see 13 cards in your hand

==== New Hand ====
We need to:

# Move all cards to the deck
# Shuffle the cards
# Deal the cards to the players

Here's the code insert infro NewHand.php state:
<pre>
// The action we do when entering the state
public function onEnteringState()
{
$game = $this->game;
// Take back all cards (from any location => null) to deck
$game->cards->moveAllCardsInLocation(null, "deck");
$game->cards->shuffle('deck');
// Deal 13 cards to each players
// Create deck, shuffle it and give 13 initial cards
$players = $game->loadPlayersBasicInfos();
foreach ($players as $player_id => $player) {
$cards = $game->cards->pickCards(13, 'deck', $player_id);
// Notify player about his cards
$this->bga->notify->player($player_id, 'newHand', '', array('cards' => $cards));
}

// reset trick color
$this->game->setGameStateInitialValue('trick_color', 0);

// FIXME: first player one with 2 of clubs
$first_player = (int) $this->game->getActivePlayerId();
$this->game->gamestate->changeActivePlayer($first_player);
return PlayerTurn::class;
}
</pre>

==== Next Player ====
Here we can handle the logic of what is the next state we need to move to:<pre>
public function onEnteringState()
{
$game = $this->game;
// Active next player OR end the trick and go to the next trick OR end the hand
if ($game->cards->countCardInLocation('cardsontable') == 4) {
// This is the end of the trick
// Select the winner
$best_value_player_id = $game->activeNextPlayer(); // TODO figure out winner of trick

// Move all cards to "cardswon" of the given player
$game->cards->moveAllCardsInLocation('cardsontable', 'cardswon', null, $best_value_player_id);

if ($game->cards->countCardInLocation('hand') == 0) {
// End of the hand
return EndHand::class;
} else {
// End of the trick
// Reset trick suite to 0
$this->game->setGameStateInitialValue('trick_color', 0);
return PlayerTurn::class;
}
} else {
// Standard case (not the end of the trick)
// => just active the next player
$player_id = $game->activeNextPlayer();
$game->giveExtraTime($player_id);
return PlayerTurn::class;
}
}
</pre>'''Important''': All state actions game or player must return the next state transition (or thrown exception).

==== Player Turn ====
We will not implement this yet, but we can throw an exception to check that the interaction is working properly.
<pre>
#[PossibleAction] // a PHP attribute that tells BGA "this method describes a possible action that the player could take", so that you can call that action from the front (the client)
public function actPlayCard(int $cardId, int $activePlayerId)
{
throw new UserException("Not implemented: $activePlayerId played card $cardId");
return NextPlayer::class; // after the action, we move to the next player
}
</pre>

==Client - Server Interactions==

Now to implement things for real we have hook UI actions to ajax calls, and process notifications sent by the server.
So previously we hooked playCardOnTable right into js handler which caused client animation, in real game its a two
step operation. When user clicks on game element js client sends an ajax call to server, server processes it and updates database, server sends
notification in response, client hooks animations to server notification.

So in .js code replace find out handStock.onCardClick and replace the handler to
<pre>
this.handStock.onCardClick = (card) => {
{
console.log("onCardClick : card ", card);
console.log("onCardClick : namestate ", this.gamedatas.gamestate.name);
if (!card) return; // hmm - should never happen
switch (this.gamedatas.gamestate.name) {
case "PlayerTurn":
// Can play a card
this.bga.actions.performAction("actPlayCard", { cardId: card.id });

break;
case "GiveCards":
// Can give cards TODO
break;
default: {
this.handStock.unselectAll();
break;
}
}
}
};

</pre>

Now reload and when you click on card you should get a server response: Not implemented...

Lets implement it, in '''PlayerTurn.php'''

We need to:

# Move the card
# Notify all player on the the move
<pre>
#[PossibleAction]
public function actPlayCard(int $cardId, int $activePlayerId)
{
$game = $this->game;
$game->cards->moveCard($cardId, 'cardsontable', $activePlayerId);
// TODO: check rules here
$currentCard = $game->cards->getCard($cardId);
// And notify
$game->notify->all('playCard', clienttranslate('${player_name} plays ${value_displayed} ${color_displayed}'), [
'i18n' => array('color_displayed', 'value_displayed'),
'card' => $currentCard,
'player_id' => $activePlayerId,
'player_name' => $game->getActivePlayerName(),
'value_displayed' => $game->card_types['types'][$currentCard['type_arg']]['name'],
'color_displayed' => $game->card_types['suites'][$currentCard['type']]['name']
]
);
return NextPlayer::class;
}
</pre>

We get the card from client, we move it to the table (moveCard is hooked to database directly, its part of deck class),
we notify all players and we change state. What we are missing here is bunch of checks (rule enforcements), we will add it later.

Interesting part about this notify is that we use i18n array for strings that needs to be translated by client, so
they are sent as English text in notification, then client has to know which parameters needs translating.

On the client side .js we have to implement a notification handler to do the animation. Below the '''setupNotification''' method (which you don't need to touch)
after <code>// TODO: from this point and below, you can write your game notifications handling methods</code>

you can put the following code:

<pre>
async notif_newHand(args) {
// We received a new full hand of 13 cards.
this.handStock.removeAll();
this.handStock.addCards(Array.from(Object.values(args.hand)));
}

async notif_playCard(args) {
// Play a card on the table
this.tableauStocks[args.player_id].addCards([args.card]);
}
</pre>

BGA will automatically bind the event to the '''notif_{eventName} handler''' which will receive the "args" you passed from php.

Refresh the page and try to play a card from the correct player. The card should move to the played area. When you refresh - you should still see the card there.
Swicth to next player using the arrows near player name and play next card.
Just before last card save the game state in "Save 1" slot (buttons in the bottom). These saves game states and you can reload it using "Load 1" later.
It is very handy.
Finish playing the trick. You will notice
after trick is done all cards remains on the table, but if you press F5 they would disappear, this is because
we updated database to pick-up the cards but did not send notification about it.

So in '''NextPlayer.php''' file add notification after // Move all cards to "cardswon" of the given player:

<pre>

// Move all win cards to cardswon location
$moved_cards = $game->cards->getCardsInLocation('cardsontable'); // remember for notification what we moved
$game->cards->moveAllCardsInLocation('cardsontable', 'cardswon', null, $best_value_player_id);

// Note: we use 2 notifications here in order we can pause the display during the first notification
// before we move all cards to the winner (during the second)
$players = $game->loadPlayersBasicInfos();
$game->notify->all('trickWin', clienttranslate('${player_name} wins the trick'), array(
'player_id' => $best_value_player_id,
'player_name' => $players[$best_value_player_id]['player_name'],

));

$game->notify->all('giveAllCardsToPlayer', '', array(
'player_id' => $best_value_player_id,
'cards' => $game->cards->getCards(array_keys($moved_cards))
));
</pre>

You notice that we passes player_name in notification because its used in the message but its pretty redundant,
as we should be able to figure out player_name by player_id.

There is a way to fix it.

in constructor of Game.php uncomment the decorator and remove second part that related to cards, so you will end up with
/* notification decorator */

$this->notify->addDecorator(function(string $message, array $args) {
if (isset($args['player_id']) && !isset($args['player_name']) && str_contains($message, '${player_name}')) {
$args['player_name'] = $this->getPlayerNameById($args['player_id']);
}

return $args;
});
Now we can remove player_name as notification argument in NextPlayer.php (and other states) and $players variable because its not used anymore.

$game->notify->all('trickWin', clienttranslate('${player_name} wins the trick'), array(
'player_id' => $best_value_player_id,
));

Now lets add these handlers in the .js file to handle our notifications:
<pre>
async notif_trickWin(args) {
// We do nothing here (just wait in order players can view the 4 cards played before they're gone)
}

async notif_giveAllCardsToPlayer(args) {
// Move all cards on table to given table, then destroy them
const winner_id = args.player_id;
const cards = Array.from(Object.values(args.cards));
await this.tableauStocks[winner_id].addCards(cards);
}
// TODO: cards has to dissapear after
}

</pre>

Ok we notice that cards that was won bunched up in ugly column and stay on tableau, but they should dissaper after trick is taken.

Now lets fix the ugly stock. We can make tableau a bit bigger to fit 4 cards or we should make cards overlap, later makes more sense since making tableau too big will be ugly.

I could not figure out how to do overlap in LineStock, AI thinks that there is attribute cardOverlap that I can set when creatingt stock, but it does not work on LineStock (as on 1.7),
so lets just add css for this in .css file

<pre>
.playertable .ha-card ~ .ha-card {
margin-left: calc(var(--h-card-width) * -0.8);
}
</pre>

This uses tilda operator that target the sibling, which is essentially all cards except first.

If you want to test that it works you can reload you test state using Load 1 button to see the finishing of a trick.

Now reload to test the trick taking - it is pretty now .

Final touch, we need card to dissapear into the void. The void we have to create first.
We need to add another node in the dom for that void stock, on server we called location "cardswon" so lets use same name, change the tableau template in .js file to this<pre>
<div id="tableau_${player.id}"/></div>
<div id="cardswon_${player.id}"/></div>
</pre>

We added cardswon (and class for tableau just in case we need it later).

Now in setup method of .js file we need to create stock for this location, in the loop where we adding tableau stock and the end of loop add this code:
// add void stock
new BgaCards.VoidStock(
this.cardsManager,
document.getElementById(`cardswon_${player.id}`),
{
autoPlace: (card) =>
card.location === "cardswon" && card.location_arg == player.id,
}
);

If you notice we did not assign this to any variable, this is because we won't need to refer to it, we will use autoPlace feature, where cardManager will know where to place it based on the location from server.
Finally we just have to modify notification handler to add this animation, this is final version (in .js file)

notif_giveAllCardsToPlayer: async function (args) {
// Move all cards on table to given table, then destroy them
const winner_id = args.player_id;

const cards = Array.from(Object.values(args.cards));
await this.tableauStocks[winner_id].addCards(cards);
await this.cardsManager.placeCards(cards); // auto-placement
},

So the function is async means it will return Promise. We are doing it so we can wait other animations to complete.
First we adding cards to player tableau, waiting for animation, then adding to our void stock where they are dissapear.

Now after the trick you see all cards move towards the "player's stash".
The animation is not ideal, so lets at void stock settings to see if can improve it: https://x.boardgamearena.net/data/game-libs/bga-cards/1.0.7/docs/classes/stocks_void-stock.VoidStock.html
Ok, well I could not figure it out, but now you know where docs for these components are.
We will do our CSS hack, in .css add:

.cardswon > .ha-card {
position: absolute;
top: 0 !important;
}

==Zombie turn==

We will implement a zombie function now because a) we have to do it at some point
b) playing 13 cards from 4 players manually to test this game is super annoying - but we can actually re-use this feature to "auto-play"

In '''PlayerTurn.php''' file, replace the zombie function with this code:
<pre>
public function zombie(int $playerId)
{
$game = $this->game;
// Auto-play a random card from player's hand
$cards_in_hand = $game->cards->getCardsInLocation('hand', $playerId);
if (count($cards_in_hand) > 0) {
$card_to_play = $cards_in_hand[array_rand($cards_in_hand)];
$game->cards->moveCard($card_to_play['id'], 'cardsontable', $playerId);
// Notify
$game->notify->all(
'playCard',
clienttranslate('${player_name} auto plays ${value_displayed} ${color_displayed}'),
[
'i18n' => array('color_displayed', 'value_displayed'),
'card' => $card_to_play,
'player_id' => $playerId,
'value_displayed' => $game->card_types['types'][$card_to_play['type_arg']]['name'],
'color_displayed' => $game->card_types['suites'][$card_to_play['type']]['name']
]
);
}
return NextPlayer::class;
}
</pre>

Now, watch this! Click Debug symbol on top bar (bug) and select function "playAutomatically" (this is actually function in your php file! it starts with debug_),
and select number of moves, i.e. 4.
If your zombie function works correctly you will see player play automatically. To play whole hand it will be 52 moves (13*4).

==Scoring and End of game handling==

Now we should calculate scoring and for that we need to actually track who wins the trick.
Trick is won by the player with highest card (no trump). We just need to remember what is trick suite.
For which we will use state variable 'trick_color' which we already conveniently created.

In '''PlayerTurn.php''' state, add this before notification
<pre>
$currenttrick_color = $game->getGameStateValue('trick_color');
if ($currenttrick_color == 0) $game->setGameStateValue('trick_color', $currentCard['type']);

</pre>

This will make sure we remember the first suit being played, now we will use it. Modify the '''NextPlayer.php''' state to fix our TODO comment in onEnteringState
<pre>
// Active next player OR end the trick and go to the next trick OR end the hand
if ($game->cards->countCardInLocation('cardsontable') == 4) {
// This is the end of the trick
$cards_on_table = $game->cards->getCardsInLocation('cardsontable');
$best_value = 0;
$best_value_player_id = $this->game->getActivePlayerId(); // fallback
$currenttrick_color = $game->getGameStateValue('trick_color');
foreach ($cards_on_table as $card) {
if ($card['type'] == $currenttrick_color) { // type is card suite
if ($best_value_player_id === null || $card['type_arg'] > $best_value) {
$best_value_player_id = $card['location_arg']; // location_arg is player who played this card on table
$best_value = $card['type_arg']; // type_arg is value of the card (2 to 14)
}
}
}

// Active this player => he's the one who starts the next trick
$this->gamestate->changeActivePlayer($best_value_player_id);

// Move all win cards to cardswon location
$win_location = 'cardswon';
$game->cards->moveAllCardsInLocation('cardsontable', $win_location, null, $best_value_player_id);
// ... notification is the same as before
</pre>

The scoring rule in the studio example code is huge multi-page function, for this tutorial we will make simplier.
Lets score -1 point per heart and call it a day. And game will end when somebody goes -100 or below.

As UI goes for scoring, the main thing to update is:

* The scoring on the mini boards represented by stars
* Show that in the log.

For a real game, you might consider showing the scoring in a [[Game_interface_logic:_yourgamename.js#Scoring_dialogs|Scoring Dialog]] using tableWindow notification, but this is out of scope of this tutorial. You can do that as homework.

In '''EndHand.php''':

<pre>
use Bga\GameFramework\NotificationMessage; // add this to the top of the file, together with the other "use" statements

...

public function onEnteringState()
{
$game = $this->game;
// Count and score points, then end the game or go to the next hand.
$players = $game->loadPlayersBasicInfos();
// Gets all "hearts" + queen of spades

$player_to_points = array();
foreach ($players as $player_id => $player) {
$player_to_points[$player_id] = 0;
}

$cards = $game->cards->getCardsInLocation("cardswon");
foreach ($cards as $card) {
$player_id = $card['location_arg'];
// Note: 2 = heart
if ($card['type'] == 2) {
$player_to_points[$player_id]++;
}
}

// Apply scores to player
foreach ($player_to_points as $player_id => $points) {
if ($points != 0) {
$game->playerScore->inc(
$player_id,
-$points,
new NotificationMessage(
clienttranslate('${player_name} gets ${absInc} hearts and looses ${absInc} points'),
)
);
}
}

///// Test if this is the end of the game
if ($game->playerScore->getMin() <= -100) {
// Trigger the end of the game !
return 99; // end game
}

return NewHand::class;
}
</pre>

The game should work now. Try to play it!
==Clean Up==
We left some code that comes from template and our first code, we should remove it now.

* In .js file remove debugger; statements if any
* Remove debug code from setupNewGame to deal cards, cards are now dealt in stNewHand state handler
// Shuffle deck
$this->cards->shuffle('deck');
// Deal 13 cards to each players
$players = $this->loadPlayersBasicInfos();
foreach ($players as $player_id => $player) {
$this->cards->pickCards(13, 'deck', $player_id);
}
* Find and remove $playerEnergy variable and it's uses from Game.php (was part of template)

==Rule Enforcements==
Now we have a working game, but there is no rule enforcement.
You can implement these rules in the '''actPlayCard''' function of '''PlayerTurn.php'''
<pre>

public function actPlayCard(int $cardId, int $activePlayerId)
{
$game = $this->game;
$card = $game->cards->getCard($cardId);
if (!$card) {
throw new \BgaSystemException("Invalid move");
}
// Rule checks

// Check that player has this card in hand
if ($card['location'] != "hand") {
throw new \BgaUserException(
clienttranslate('You do not have this card in your hand')
);
}
$currenttrick_color = $game->getGameStateValue('trick_color');
// Check that player follows suit if possible
if ($currenttrick_color != 0) {
$has_suit = false;
$hand_cards = $game->cards->getCardsInLocation('hand', $activePlayerId);
foreach ($hand_cards as $hand_card) {
if ($hand_card['type'] == $currenttrick_color) {
$has_suit = true;
break;
}
}
if ($has_suit && $card['type'] != $currenttrick_color) {
throw new \BgaUserException(
clienttranslate('You must follow suit')
);
}
}

</pre>
You can try to play wrong card now and you will see error!
But you noticed we broke the zombie mode as you cannot play random card anymore and now uThe user cannot play ANY card, there are only some cards they can play but we don't show this information which is annoying.
To fix this we can add a helper function that will return a list of playable cards for a given player.
Add these functions in '''Game.php''' file:
<pre>
function getPlayableCards($player_id): array
{
// Get all data needed to check playable cards at the moment
$currentTrickColor = $this->getGameStateValue('trick_color');
$broken_heart = $this->brokenHeart();
$total_played = $this->cards->countCardInLocation('cardswon') + $this->cards->countCardInLocation('cardsontable');
$hand = $this->cards->getPlayerHand($player_id);

$playable_card_ids = [];
$all_ids = array_keys($hand);

if ($this->cards->getCardsInLocation('cardsontable', $player_id)) return []; // Already played a card

// Check whether the first card of the hand has been played or not
// if ($total_played == 0) {
// // No cards have been played yet, find and return the starter card only
// foreach ($hand as $card) if ($card['type'] == 3 && $card['type_arg'] == 2) return [$card['id']]; // 2 of clubs
// return [];
// } else
if (!$currentTrickColor) { // First card of the trick
if ($broken_heart) return $all_ids; // Broken Heart or no limitation, can play any card
else {
// Exclude Heart as Heart hasn't been broken yet
foreach ($hand as $card) if ($card['type'] != 2) $playable_card_ids[] = $card['id'];
if (!$playable_card_ids) return $all_ids; // All Heart cards!
else return $playable_card_ids;
}
} else {
// Must follow the lead suit if possible
$same_suit = false;
foreach ($hand as $card)
if ($card['type'] == $currentTrickColor) {
$same_suit = true;
break;
}
if ($same_suit) return $this->getObjectListFromDB("SELECT card_id FROM card WHERE card_type = $currentTrickColor AND card_location = 'hand' AND card_location_arg = $player_id", true); // Has at least 1 card of the same suit

else return $all_ids;
}
}

function brokenHeart(): bool
{
// Check Heart in the played card piles
return (bool)$this->getUniqueValueFromDB("SELECT count(*) FROM card WHERE card_location = 'cardswon' AND card_type = 2");
}

function tableHeart(): bool
{
// Check Heart in the current trick
return (bool)$this->getUniqueValueFromDB("SELECT count(*) FROM card WHERE card_location = 'cardsontable' AND card_type = 2");
}

</pre>

Now we can use this function in the zombie function of '''PlayerTurn.php''' to pick a random playable card:
<pre>
public function zombie(int $playerId)
{
$playable_cards = $this->game->getPlayableCards($playerId);
$zombieChoice = $this->getRandomZombieChoice($playable_cards); // random choice over possible moves
return $this->actPlayCard((int)$zombieChoice, $playerId);
}
</pre>

And we can significantly simplify our rule check at actPlayCard
<pre>
$game = $this->game;
$currentCard = $game->cards->getCard($cardId);
if (!$currentCard) {
throw new \BgaSystemException("Invalid move");
}
// Rule checks
$playable_cards = $game->getPlayableCards($activePlayerId);
if (!in_array($cardId, $playable_cards)) {
throw new \BgaUserException(clienttranslate("You cannot play this card now"));
}

</pre>
Finally we can send this to the client via state args so the user can see what moves are valid:
In '''PlayerTurn.php''' add this method:
<pre>
public function getArgs(int $activePlayerId): array
{
// Send playable card ids of the active player privately
return [
'_private' => [
$activePlayerId => [
'playableCards' => $this->game->getPlayableCards($activePlayerId)
],
],
];
}
</pre>
On the client side in the .js file replace the onEnteringState method with this code (and ALSO remove the this.handStock.setSelectionMode("single") line from the setup method. If you leave it there it won't work as this is async function that collide with our other async
functions that we are using in the onEnteringState):
<pre>
onEnteringState(args, isCurrentPlayerActive) {
console.log("Entering state: " + this.bga.states.currentStateName, args);

this.bga.statusBar.setTitle(
isCurrentPlayerActive
? _("${you} must play a card")
: _("${actplayer} must play a card"),
);

switch (stateName) {
case "PlayerTurn":
if (isCurrentPlayerActive) {
const playableCardsIds = args.playableCardsIds; // returned by the PlayerTurn::getArgs
const allCards = this.game.handStock.getCards();
const playableCards = allCards.filter(
(card) => playableCardIds.includes(parseInt(card.id)) // never know if we get int or string, this method cares
);
this.game.handStock.setSelectionMode("single", playableCards);
}
break;
}
},
</pre>

==Fix first player with 2 of clubs==

Find the comment
// FIXME: first player one with 2 of clubs
and replace with this code:
// first player one with 2 of clubs
$first_player = $this->game->getUniqueValueFromDb("SELECT card_location_arg FROM card WHERE card_location = 'hand' AND card_type = 3 AND card_type_arg = 2");// 2 of clubs

Then we can uncomment our code for getPlayableCards in Game.php:
//Check whether the first card of the hand has been played or not
$total_played = $this->cards->countCardInLocation('cardswon') + $this->cards->countCardInLocation('cardsontable');
if ($total_played == 0) {
// No cards have been played yet, find and return the starter card only
foreach ($hand as $card) if ($card['type'] == 3 && $card['type_arg'] == 2) return [$card['id']]; // 2 of clubs
return $all_ids; // should not happen
} else

==Spectator support==
A spectator is not a real player but they can watch the game. Most games will require special spectator support, it's one of the steps in the alpha testing checklist.
In this game it's pretty simple, we just hide the hand control in the client

In the .js file in the setup function add this code (after DOM is created):
// Hide hand zone from spectators
if (this.isSpectator)
document.getElementById("myhand_wrap").style.display = "none";

Click Test Spectator at the end of player's panels to test this.

==Improve UI==
We need to fix a few things in the UI still.

===Center Player Areas===
First let's fix the player tables - to make them centered.
In the .css file find #player-tables and change it to this:

#player-tables {
position: relative;
width: calc(var(--h-tableau-width) * 3.8);
height: calc(var(--h-tableau-height) * 2.4);
margin: auto; // that is a cheap way to make it centered
}

===Better Card Play Animations===
When another player plays a card it kind of just appears on the tableau, we want to make it look like it's coming from the player hand.
We don't actually have any sort of UI location to have a player hand - but we can either put it on the mini player panel or add it to the bottom of the player areas.
Let's try to put this on the mini player panels.
First we need to add a node in the DOM on the player panel and maybe add an icon to represent the hand.
We have access to some BGA icons and font awesome icons https://fontawesome.com/v4/icons, so we can pick one from there:

In the .js file in the template for player tableau and add this at the end of the forEach body:
<pre>
document.getElementById(`player_panel_content_${player.color}`).innerHTML =
`<div id="otherhand_${player.id}" class="otherhand"><i class="fa fa-window-restore"></i></div>`;
</pre>
In the .js file replace the notif handler for play with this:
<pre>
async notif_playCard(args) {
// Play a card on the table
const playerId = args.player_id;
let settings = {};
if (playerId != this.player_id) {
settings = {
fromElement: $(`otherhand_${playerId}`),
toPlaceholder: "grow",
};
}
await this.tableauStocks[playerId].addCard(args.card, settings);
},
</pre>
What we did here is added a settings parameter for card placement - for cases where it's not our own card to move it from the "hand" area on the mini player board.
Reload and test (use the autoPlay feature to see the animation when the "other" player plays the card).

Now we can also replace the void stock we create with animation to the same "otherhand" area:
<pre>
async notif_giveAllCardsToPlayer(args) {
// Move all cards from notification to dedicated player area and fade out
const playerId = args.player_id;

const cards = Array.from(Object.values(args.cards));
await this.tableauStocks[playerId].addCards(cards);
await this.tableauStocks[playerId].removeCards(cards, {
fadeOut: true,
slideTo: $(`otherhand_${playerId}`),
});
},
</pre>
And in this case we don't really need VoidStock anymore, we can remove it
Delete this
<pre>
// add void stock
new BgaCards.VoidStock(
this.cardsManager,
document.getElementById(`cardswon_${playerId}`),
{
fadeOut: true, // not working
toPlaceholder: "shrink", // not working
autoPlace: (card) =>
card.location === "cardswon" && card.location_arg == playerId,
}
);
</pre>
Also can delete related css and DOM element cardswon.

We can also add this in .css to make this symbol centered:
.otherhand {
position: relative;
margin: auto;
text-align: center;
}

===Card Sorting===
It would be nice to sort the cards in hand by suit and value.
You can add sorting
// create the stock, in the game setup
this.handStock = new BgaCards.HandStock(
this.cardsManager,
document.getElementById("myhand"),
{
sort: BgaCards.sort('type', 'type_arg'), // sort by suite then by value
}
);

but you will notice its not sorted right.
Its because of type mismatch. The server sends us strings and bga-cards expects integers.
We have to change this on client or server. I was already doing some ugly convertion on client, so lets just make it official.
We will add 2 functions in utility section that will do the convertions for us:
///////////////////////////////////////////////////
//// Utility methods

remapToBgaCardList: function (cards) {
if (!cards) return [];
if (cards.type) {
// actually one card
return [this.remapToBgaCard(cards)];
} else if (Array.isArray(cards)) {
return cards.map((card) => this.remapToBgaCard(card));
} else {
return Object.values(cards).map((card) => this.remapToBgaCard(card));
}
},
remapToBgaCard: function (card) {
// proper casts
return {
id: parseInt(card.id),
type: parseInt(card.type),
type_arg: parseInt(card.type_arg),
location: card.location,
location_arg: parseInt(card.location_arg),
};
},
Then in setup change addCards to this
this.handStock.addCards(this.remapToBgaCardList(this.gamedatas.hand));
and
// Cards played on table
for (i in this.gamedatas.cardsontable) {
var card = this.gamedatas.cardsontable[i];
var player_id = card.location_arg;
this.tableauStocks[player_id].addCard(this.remapToBgaCard(card));
}

In notif_newHand replace addCards like this:
this.handStock.addCards(this.remapToBgaCardList(args.hand));

In notif_giveAllCardsToPlayer
const cards = this.remapToBgaCardList(args.cards);
In notif_playCard
await this.tableauStocks[playerId].addCard(this.remapToBgaCard(args.card), settings);

Now sorting should work!

An alternative the above is to not change card types and sub types but rather to sort the cards using something like this
sortCards(cards) {
return Array.from(cards).sort(function (a, b) {
// sort by suit then rank
// sort by suit then rank
if (a.type === b.type) {
// sub sort by rank
return parseInt(a.type_arg) - parseInt(b.type_arg);
} else {
// sort by suit
return parseInt(a.type) - parseInt(b.type);
}
});
}

===Tooltips===
We can add tooltips to cards to show their name.
In the .js file find where created silly tooltip with addTooltipHtml and replace with this:
this.bga.gameui.addTooltipHtml(div.id,
_(this.gamedatas.card_types.types[card.type_arg].name)+ " " +
_(this.gamedatas.card_types.suites[card.type].name)
);
Now what is this.gamedatas.card_types? Well that is our "material" of the game which is in our case variable in php, we have to send it to client for this to work.
Since it never changes we send it in getAllDatas method, add this at the end before return:
$result['card_types'] = $this->card_types;

Of course this is very basic tooltips and not even needed in this game, but in real game your want tooltips everywhere!!!
Lets add tooltip to our fake hand symbol also (the "otherhand") (in setup method in .js somewhere in forEach loop over players)
// add tooltips to player hand symbol
this.bga.gameui.addTooltipHtml(
`otherhand_${playerId}`,
_("Placeholder for player's hand")
);

==Game progresstion==
In this game it should be easy, we just need to know if somebody close to -100 points!
Find getGameProgression in Game.php and replace with this:
public function getGameProgression()
{
$min = $this->playerScore->getMin();
return -1 * $min; // we get close to -100 we get close to 100% game completion
}

==Additional stuff==

The following things were not implemented and you can add them yourself by looking at the code of the original hearts game:

*Mark player who started the hand and add log about what is starting Suite of the trick
*Start scoring with 100 points each and end when <= 0
*Fix scoring rules with Q of spades and 26 point reverse scoring
*Add statistics
*Add card exchange states
*Add game option to start with 75 points instead of 100

==After the tutorial==
You might want to check another tutorial, or start working on your first real project!

[[Create a game in BGA Studio: Complete Walkthrough]]
[[Category:Studio]]

Tutorial hearts

2026-03-16T22:48:02Z

RichardSPeters: Small changes to bring tutorial in line with current framework to make following the turorial easier

{{Studio_Framework_Navigation}}

== Introduction ==

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

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

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

== Hearts Rules ==

Hearts is a trick-taking card game for four players where the goal is to score the fewest points.
Players aim to avoid taking tricks with heart cards (1 point each) and the Queen of Spades (13 points).
Each round, 13 cards are dealt, players pass three cards, and the player with the 2 of Clubs starts the first trick.
Play continues clockwise, with players needing to follow suit if they can, and the highest card of the lead suit wins the trick.
Hearts cannot be played until they are "broken" by a player who can't follow suit and discards a heart, or by a player leading with a heart after they've been broken.

== Create your first game ==

If you have not already, you have to create a project in BGA Studio. For this tutorial you can create a project heartsYOURNAME where
YOURNAME is your developer login name (or shorter version of thereof). You can also re-use the project you have created for the "First Steps" tutorial above.

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

With the initial skeleton of code provided, you can already start a game from the BGA Studio.

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

2. Modify the text in .js file (for example replace "Player zone content goes here" to "Hello"), reload the page in the browser and make sure your ftp sync works as expected.
Note: if you have not setup auto-sync do it now, manually copying files is a no-starter.

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

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

== Hook version control system ==

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

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

Different revisions represent different steps along the process, starting from original template to a PARTIAL game.

Note: the game was re-written using new template, the old code is in "oldframework" branch. The new template is in main branch.

The real hearts game (that you can play on BGA) can be found in your FTP home folder, after getting read-only access, go to https://studio.boardgamearena.com/projects, select Already Published and find Hearts to get access
(It may not match this tutorial as framework diverged since this game was created and it may not have been updated)

== Update game infos and box graphics ==

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

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

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

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

// Game publisher
'publisher' => 'Public Domain',

// Board Game Geek ID of the publisher
'publisher_bgg_id' => 171,

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

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

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

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

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

== Layout and Graphics ==

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

First copy a sprite with cards image from [https://x.boardgamearena.net/data/others/cards/FULLREZ_CARDS_ORIGINAL_NORMAL.jpg] into img/cards.jpg folder of your project.

Details about images can be found here: [[Game art: img directory]]. If you did not setup auto-sync of files, sync the graphics manually with remote folder (re-sync with your workspace).

Edit .js to add some divs to represent player table and hand area, at the beginning of the setup function

<pre>

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

this.bga.gameArea.getElement().insertAdjacentHTML(
"beforeend",
`
<div id="myhand_wrap" class="whiteblock">
<b id="myhand_label">${_("My hand")}</b>
<div id="myhand">
</div>
</div>

`,
);
// ...
</pre>

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

[[File:Heartsla-tpl2.png]]

Now lets add a card into the hand, just so you can feel it. Edit the html snippet we inserted earlier buy adding a line representing a card
<pre>
...
<div id="myhand">
<div class="fakecard"></div>
</div>
...
</pre>

Edit .css file, add this code (.css file is empty now, only has comments, just tuck this at the end)
<pre>
.fakecard {
display: inline-block;
position: relative;
margin-top: 5px;
border-radius: 5%;
width: 100px;
height: 135px;
background-size: calc(100px * 15);
background-image: url('img/cards.jpg'); /* temp hack to see it */
}
</pre>

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

You should see this (more less):

[[File:Heartsla-tpl3.png]]

Note: If you don't see the card a) check it was synced to remote folder b) force reload page

Awesome! Now lets do the rest of layout.

Let's complete the game template. You template should have this code, just leave it there
<pre>

// Example to add a div on the game area
this.bga.gameArea.getElement().insertAdjacentHTML("beforeend",
<div id="player-tables"></div>
`
);
</pre>

Then change the code following comment "// Setting up player boards" with this
<pre>
// Setting up player boards
const numPlayers = Object.keys(gamedatas.players).length;
Object.values(gamedatas.players).forEach((player, index) => {
document.getElementById("player-tables").insertAdjacentHTML(
"beforeend",
// we generate this html snippet for each player
`
<div class="playertable whiteblock playertable_${DIRECTIONS[index]}">
<div class="playertablename" style="color:#${player.color};">${player.name}</div>
<div id="tableau_${player.id}"></div>
</div>
`
);
});
</pre>
What we did is we added a template for every players at the table.
Now try to reload you game.
Oops! it won't load. This is to teach you how it will look like when you have syntax error in your js file. The game will hang loading at 10% or so. How to know what happened?
Open dev tools in browser (usually F12) and navigate to Console tab. You will see a stack trace of where error is. In our case
HeartsFIXME.js:68 Uncaught (in promise) ReferenceError: DIRECTIONS is not defined

In real hearts game they use this direction array to map every player to direction (like North) but its not needed, we can just use player index.
Lets just replace DIRECTIONS[index] with index, i.e
<div class="playertable whiteblock playertable_${index}">

Now delete the following section as we won't be using it<pre>
// Add test action buttons in the action status bar, simulating a card click:
playableCardsIds.forEach((cardId) =>
this.bga.statusBar.addActionButton(
_("Play card with id ${card_id}").replace("${card_id}", cardId),
() => this.onCardClick(cardId),
),
);

this.bga.statusBar.addActionButton(
_("Pass"),
() => this.bga.actions.performAction("actPass"),
{ color: "secondary" },
);

</pre>

Reload. If everything went well you should see this:

[[File:Heartsla-tpl4.png|alt=Display player space of all players]]

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

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

<pre>
:root {
--h-card-width: 100px;
--h-card-height: 135px;
--h-tableau-width: 220px;
--h-tableau-height: 180px;
}

#player-tables {
position: relative;
width: calc(var(--h-tableau-width) * 3.9);
height: calc(var(--h-tableau-height) * 2.4);
}

.playertablename {
font-weight: bold;
}

.playertable {
position: absolute;
text-align: center;
width: var(--h-tableau-width);
height: var(--h-tableau-height);
}

.playertable_0 {
top: 0px;
left: 50%;
margin-left: calc(var(--h-tableau-width) / 2 * -1);
}

.playertable_1 {
left: 0px;
top: 50%;
margin-top: calc(var(--h-tableau-height) / 2 * -1);
}
.playertable_2 {
right: 0px;
top: 50%;
margin-top: calc(var(--h-tableau-height) / 2 * -1);
}
.playertable_3 {
bottom: 0px;
left: 50%;
margin-left: calc(var(--h-tableau-width) / 2 * -1);
}
</pre>

and delete the following section from game.js as we won't be using it<pre>
// example of adding a div for each player
document.getElementById("player-tables").insertAdjacentHTML(
"beforeend",
`
<div id="player-table-${player.id}">
<strong>${player.name}</strong>
<div>Player zone content goes here</div>
</div>
`,
);

</pre>

Now you force Reload and you should see this:

[[File:Heartsla-tpl5.png]]

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

Here is some explanations about CSS (if you know everything about css already skip this):
* At top we defined some variables for sizes of cards and player "mats" (which we call tableau)
* We trying to layout mats in kind of diamond shape
* We define positions of our elements using top/bottom/left/right style property
* We used standard technique of centering the element which is use 50% for lets say "left", and then shift by half of size of object to actually center it (margin-left). You can remove margins to see how it look if we did not do that

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

== Game Interface with BGA Cards ==

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

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

First, we need to add dependencies in the Game.js file:
<pre>
const BgaAnimations = await importEsmLib('bga-animations', '1.x');
const BgaCards = await importEsmLib('bga-cards', '1.x');
</pre>

Now we will remove the fake card we added (in Game.js file) search and remove: <pre>
<div id="myhand">
<div class="fakecard"></div>
</div>
</pre>

Then we will add initialization code of bga cards and related component in setup method after the template code (i.e. where we defined the myhand div as this div is referenced by the following code) and before setupNotifications <pre>
// create the animation manager, and bind it to the `game.bgaAnimationsActive()` function
this.animationManager = new BgaAnimations.Manager({
animationsActive: () => this.bga.gameui.bgaAnimationsActive(),
});

const cardWidth = 100;
const cardHeight = 135;

// create the card manager
this.cardsManager = new BgaCards.Manager({
animationManager: this.animationManager,
type: "ha-card", // the "type" of our cards in css
getId: (card) => card.id,

cardWidth: cardWidth,
cardHeight: cardHeight,
cardBorderRadius: "5%",
setupFrontDiv: (card, div) => {
div.dataset.type = card.type; // suit 1..4
div.dataset.typeArg = card.type_arg; // value 2..14
div.style.backgroundPositionX = `calc(100% / 14 * (${card.type_arg} - 2))`; // 14 is number of columns in stock image minus 1
div.style.backgroundPositionY = `calc(100% / 3 * (${card.type} - 1))`; // 3 is number of rows in stock image minus 1
this.bga.gameui.addTooltipHtml(div.id, `tooltip of ${card.type}`);
},
});

// create the stock, in the game setup
this.handStock = new BgaCards.HandStock(
this.cardsManager,
document.getElementById("myhand")
);
// TODO: fix handStock
this.handStock.addCards([
{ id: 1, type: 2, type_arg: 4 }, // 4 of hearts
{ id: 2, type: 3, type_arg: 11 }, // Jack of clubs
]);
</pre>

Also we need to add this .css (anywhere), that will map front face of the card to our image (1500% is because this image 15 times bigger than single card on X axis)
<pre>
.ha-card-front {
background-size: 1500% auto;
background-image: url("img/cards.jpg");
}
</pre>

Explanations:
* First we created animation manager which will be used later
* Then we define constant with width and height of our cards in pixes
* Then we create the cards manager. We tell it how to get unique id of each card (getId), and how to setup the div representing the front of the card (setupFrontDiv). In this function we set data attributes for type and type_arg which we will use later, and we set background position to show correct part of sprite image.
* Then we create a hand stock component which will represent player's hand. It is attached to div with id "myhand".
* Finally we add two cards into the hand stock just for testing.

Now if you reload you should see two cards in your hand:

[[File:Heartsla-tpl6.png|alt=Display two cards in player's hand]]

Now we will add the "stock" object that will control player tableau (add in setup function before setupNotification)
<code>

// map stocks

this.tableauStocks = [];
Object.values(gamedatas.players).forEach((player, index) => {
// add player tableau stock
this.tableauStocks[player.id] = new BgaCards.LineStock(
this.cardsManager,
document.getElementById(`tableau_${player.id}`)
);

// TODO: fix tableauStocks
this.tableauStocks[player.id].addCards([
{ id: index + 10, type: index + 1, type_arg: index + 2 },
]);
});

</code>

[[File:Heartsla-tpl7.png]]

Explanations:
* We go over each player and create component called LineStock to represent player tableau, it will hold a single card
* We assign this into tableauStocks map indexed by player id to use later
* Finally we add a fake card into that stock just to see something

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

Let's hook it up. Add this in the setup method in .js file, before // TODO: fix handStock:

this.handStock.setSelectionMode("single");
this.handStock.onCardClick = (card) => {
alert("boom!");
};

Reload the game and click on one of the two Cards in your hand. You should get "boom".

We will stop for now with client because we need to code some server stuff.

== Game Database and Game Initialization ==

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

==== Database Schema ====
When you develop a game you need to figure out how you store your game pieces in database. This should be maximum 2 tables (like one for cards, items, tokens and meeples and one for counters).
In this game we will be using two tables, the default Deck table (supported by Deck component) and default "state variables" tables which called globals, to store some of integers.
In you never dealt with web servers - the database stores all information about your game and your php (server) code does not exists in memory between users actions.

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

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

This is how we map the database to our game:
* card_id: unique id of each card, it will be auto-generated
* card_type: it will be suite of the card 1 to 4 (Spades,Hearts,Clubs,Diamonds).
* card_type_arg: will be "value" of the card, 2 to 14 (2 is 2,...,10 is 10, 11 is Jack, ...)
* card_location: will be location of the card, like "deck", "hand", "tableau" etc
* card_location_arg: will be additional argument for location - the player id if card is in player's hand or tableau.

=== Game State Variables ===
<pre>
CREATE TABLE IF NOT EXISTS `card` (
`card_id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`card_type` varchar(16) NOT NULL,
`card_type_arg` int(11) NOT NULL,
`card_location` varchar(16) NOT NULL,
`card_location_arg` int(11) NOT NULL,
PRIMARY KEY (`card_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>Next we finally get into Game.php class (in modules/php subdir), where the main logic and db interaction would be. Find php constructor which should be
function __construct( )
This is first function in a file. Add this code to constructor (replace existing initGameStateLabel if any).
<pre>
public function __construct()
{
parent::__construct();
$this->initGameStateLabels(
[
"trick_color" => 11,
]
);

$this->cards = $this->deckFactory->createDeck('card'); // card is the our database name
// ...
</pre>

If you see errors in IDE its because we also have to declared "cards" as class member, add ''public Deck $cards;'' before the contructor.
Also if you using IDE it will suggest to import Deck class, accept it. If you are using 'vi' just add this import where other imports (use in php) at the begging of the file after namespace declaration.

use Bga\GameFramework\Components\Deck;

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

The variables are:

*"trick_color": numbers from 1 to 4 that map to card suit (not sure why it's called color; maybe it's a translation from French);

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

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

Note: if you have some other leftovers from template like playerEnergy, leave it for now as is.

Since we changed the database schema, we cannot re-use our existing game, we have to do express stop (from burger menu).

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

If you game won't even load and you want to stop it:
https://en.doc.boardgamearena.com/Tools_and_tips_of_BGA_Studio#Stopping_Hanging_Game

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

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

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

</pre>

Here we initialize all the globals to 0.

Next is to create our cards in the database. We have one deck of cards so it's pretty simple.
Insert this after // TODO: Setup the initial game situation here.

<pre>
// Create cards
$cards = [];
foreach ($this->card_types["suites"] as $suit => $suit_info) {
// spade, heart, diamond, club
foreach ($this->card_types["types"] as $value => $info_value) {
// 2, 3, 4, ... K, A
$cards[] = ['type' => $suit, 'type_arg' => $value, 'nbr' => 1];
}
}
$this->cards->createCards($cards, 'deck');
</pre>

This code that will create one of each card. But don't run it yet, because we missing ''card_types''.
So we have state of the game in the database, but there is some static game information which never changes.
This information should be stored in .php and this way it can be accessed from all .php files (and .js if you send it via getAllDatas()).

Note: originally it was stored in material.inc.php file which is no longer part of default template, when you have a lot of material it makes sence to get it out of Game.php

We will edit Game.php now by adding these lines in constructor (and replacing ''self::$CARD_TYPES'')

<pre>
$this->card_types = [
"suites" => [
1 => [
'name' => clienttranslate('Spade'),
],
2 => [
'name' => clienttranslate('Heart'),
],
3 => [
'name' => clienttranslate('Club'),
],
4 => [
'name' => clienttranslate('Diamond'),
]
],
"types" => [
2 => ['name' => '2'],
3 => ['name' => '3'],
4 => ['name' => '4'],
5 => ['name' => '5'],
6 => ['name' => '6'],
7 => ['name' => '7'],
8 => ['name' => '8'],
9 => ['name' => '9'],
10 => ['name' => '10'],
11 => ['name' => clienttranslate('J')],
12 => ['name' => clienttranslate('Q')],
13 => ['name' => clienttranslate('K')],
14 => ['name' => clienttranslate('A')]
]
];

</pre>

If you pass a value to the client via notification you should always use untranslated strings, and the client will translate it. Function 'clienttranslate' marks the value for translation but does not actually change it for php. For more about this wonderful translation stuff see [[Translations]].

Can also have declared this in the class (replace $CARD_TYPES)
public array $card_types;

Reload to make it still works (no errors).

==== Dealing Cards ====
After we have initialized our deck, we want to deal 13 at random for each player. Add this after createCards in setupNewGame function in the Game.php file:
<pre>
// Shuffle deck
$this->cards->shuffle('deck');
// Deal 13 cards to each players
$players = $this->loadPlayersBasicInfos();
foreach ($players as $player_id => $player) {
$this->cards->pickCards(13, 'deck', $player_id);
}

</pre>
In the next section we are going to learn how to show those cards to the right players, without exposing other player hands.

==Full Game Model Synchronization==

Now at any point in the game we need to make sure that database information can be reflected back in the UI, so we must fix the '''getAllDatas''' function
to return all possible data we need to reconstruct the game. This is in the Game.php file.

=== Player's Hand ===
The template for getAllDatas() already takes care of player info. Let's just
add hand and tableau data before we return a result.

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

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

Now on the client side we should display this data, so in your game.js file in the setup function (which is the receiver of getAllDatas), find // TODO: fix handStock
and replace our hack of putting cards directly into the hand with:

<pre>
// Cards in player's hand
this.handStock.addCards(Array.from(Object.values(this.gamedatas.hand)));

</pre>
So we added all cards from server to the hand stock. Have to do this ugly array convertion, hopefully they will fix addCards so we don't need to do this.

At this point, you have to RESTART a game and each player should see their hand!

At any point if code does not work on clinet side, add command "debugger;" in the code. In browser press F12 to get dev tools, then reload.
You will hit breakpoint and can you in browser debugger. Don't forget to remove debugger; code after.

=== Cards on Table ===
Now lets fix out tableau, find comment in setup method of .js file // TODO: fix tableau
and remove stock.addCards... from that loop. But right after this add
// Cards played on table
for (i in this.gamedatas.cardsontable) {
var card = this.gamedatas.cardsontable[i];
var player_id = card.location_arg;
this.tableauStocks[player_id].addCards([card]);
}

If you reload now you can see nothing on the table.

Next, we will hook-up clicking on card and test if our animation.

Find the "boom" we put in the click handler. Replace with this
this.handStock.onCardClick = (card) => {
this.tableauStocks[card.location_arg].addCards([card]);
};

Now if you reload you should be able to click on card from your hand and see it moving,
you can click on few cards this way. When you done enjoying the animation, press F5 to get your hand back.

[[File:Heartsla-sync.png]]

==State Machine==

Stop the game. We are about to work on the game logic.

You already read [http://www.slideshare.net/boardgamearena/bga-studio-focus-on-bga-game-state-machine Focus on BGA game state machine], so you know that this is the heart of your game logic.
Note: ignore all the source snippets in this presentation, as framework changed, just note the concepts.

Here are the states we need to build (excluding two more states we will add later to handle the exchange of cards at the beginning of the rounds):

*Cards are dealt to all players (lets call it "NewHand")
*Player start or respond to played card ("PlayerTurn")
*Game control is passed to next player or trick is ended ("NextPlayer")
*End of hand processing (scoring and check for end of game) ("EndHand")

Note: if you find states.inc.php file in top level directory - delete it now.

=== State Templates ===
We will create just barebones state files first:

==== States/NewHand.php ====
Let's create our first state - "NewHand". Create a new file under "module/php/States" and name it "'''NewHand.php'''".
<pre>

<?php
declare(strict_types=1);
namespace Bga\Games\HeartsFIXME\States;

use Bga\Games\HeartsFIXME\Game;
use Bga\GameFramework\StateType;
use Bga\GameFramework\States\GameState;

class NewHand extends GameState
{
public function __construct(protected Game $game)
{
parent::__construct(
$game,
id: 2, // the idea of the state
type: StateType::GAME, // This type means that no player is active, and the game will automatically progress
updateGameProgression: true, // entering this state can update the progress bar of the game
);
}

// The action we do when entering the state
public function onEnteringState()
{
return PlayerTurn::class;
}
}

</pre>
You can read more about it here: [[State classes: State directory]]

If you use IDE you see few errors:
* First there is no Bga\Games\HeartsFIXME\Game - that is because you games is not called HeartsFIXME, is something like HeartsFooBar - so you change this and namespace to your game name.
* Second it will compain abot NewTrick class - it does not exist yet

Let's implement the other states:

==== States/PlayerTurn.php ====
If file exists replace its content.
This action is different because it has an action a player must take. Read the comments in the code below to understand the syntax:
<pre>
<?php

declare(strict_types=1);

namespace Bga\Games\HeartsFIXME\States;

use Bga\Games\HeartsFIXME\Game;
use Bga\GameFramework\StateType;
use Bga\GameFramework\States\PossibleAction;
use Bga\GameFramework\States\GameState;
use Bga\GameFramework\UserException;

class PlayerTurn extends GameState
{
public function __construct(protected Game $game)
{
parent::__construct(
$game,
id: 31,
type: StateType::ACTIVE_PLAYER, // This state type means that one player is active and can do actions
description: clienttranslate('${actplayer} must play a card'), // We tell OTHER players what they are waiting for
descriptionMyTurn: clienttranslate('${you} must play a card'), // We tell the ACTIVE player what they must do
// We suround the code with clienttranslate() so that the text is sent to the client for translation (this will enable the game to support other languages)
);
}

#[PossibleAction] // a PHP attribute that tells BGA "this method describes a possible action that the player could take", so that you can call that action from the front (the client)
public function actPlayCard(int $cardId, int $activePlayerId)
{
// TODO: implement logic
return NextPlayer::class; // after the action, we move to the next player
}

public function zombie(int $playerId)
{
// We must implement this so BGA can auto play in the case a player becomes a zombie, but for this tutorial we won't handle this case
throw new UserException('Not implemented: zombie for player ${player_id}');
}
}

</pre>
You would also notice the "zombie" method. This would allow BGA to auto-player for the player if they became inactive. This is mandatory, but we will implement this later.

==== States/NextPlayer.php ====
This state have a couple of different options for what would be the next state:

* If not all players played a card in the current trick - we need to go to '''PlayerTurn''' (for the next player)
* If all players finished the trick but still have cards in their hand - we need to go to '''PlayerTurn'''
* If this is the last trick (no more cards in end) and it's finished, we need to go to '''EndHand'''

We will implement this logic later. For now let's return '''NewHandPlayerTurn''' (see onEnteringState).
<pre>
<?php
declare(strict_types=1);
namespace Bga\Games\HeartsFIXME\States;

use Bga\GameFramework\StateType;
use Bga\Games\HeartsFIXME\Game;
use Bga\GameFramework\States\GameState;

class NextPlayer extends GameState
{
public function __construct(protected Game $game)
{
parent::__construct(
$game,
id: 32,
type: StateType::GAME,
);
}

public function onEnteringState()
{
return PlayerTurn::class;
}
}

</pre>

==== States/EndHand.php ====
Here too we will have two options for transition, either we play another hand ('''NewHand''') or we finish the game (a reserved id for finishing the game is '''99''').

We will implement this logic later. For now let's return '''NewHand''' (see onEnteringState).

<pre>
<?php
declare(strict_types=1);
namespace Bga\Games\HeartsFIXME\States;

use Bga\GameFramework\StateType;
use Bga\Games\HeartsFIXME\Game;
use Bga\GameFramework\States\GameState;

class EndHand extends GameState
{
public function __construct(protected Game $game)
{
parent::__construct(
$game,
id: 40,
type: StateType::GAME,
description: "",
);
}

public function onEnteringState()
{
// TODO: implement logic
return NewHand::class;
}
}

</pre>

Check again that no HeartsFIXME left in the code, if yes replace with game name.

Remove EndScore.php - don't need it.

Don't start the game yet, it won't load, we have to clean up bunch of template code in the .js

=== Test Your Game is not broken ===
We changed state related logic, so we need to restart the game. If the game starts without error we are good. We won't be able to test the interactions yet because we need to implement the client side.

Think the following is from the old framework and no longer relevant.

<s>Since we added bunch of different states we need to remove some more templace code, in .js file find onUpdateActionButtons, and remove all functional code, leaving just this</s><pre>
onUpdateActionButtons: function (stateName, args) {
console.log("onUpdateActionButtons: " + stateName, args);

if (this.isCurrentPlayerActive()) {
switch (stateName) {
case "playerTurn":
break;
}
}
},
</pre>

=== State Logic ===
Now if you RESTART the game, it should not crash and you see 13 cards in your hand

==== New Hand ====
We need to:

# Move all cards to the deck
# Shuffle the cards
# Deal the cards to the players

Here's the code insert infro NewHand.php state:
<pre>
// The action we do when entering the state
public function onEnteringState()
{
$game = $this->game;
// Take back all cards (from any location => null) to deck
$game->cards->moveAllCardsInLocation(null, "deck");
$game->cards->shuffle('deck');
// Deal 13 cards to each players
// Create deck, shuffle it and give 13 initial cards
$players = $game->loadPlayersBasicInfos();
foreach ($players as $player_id => $player) {
$cards = $game->cards->pickCards(13, 'deck', $player_id);
// Notify player about his cards
$this->bga->notify->player($player_id, 'newHand', '', array('cards' => $cards));
}

// reset trick color
$this->game->setGameStateInitialValue('trick_color', 0);

// FIXME: first player one with 2 of clubs
$first_player = (int) $this->game->getActivePlayerId();
$this->game->gamestate->changeActivePlayer($first_player);
return PlayerTurn::class;
}
</pre>

==== Next Player ====
Here we can handle the logic of what is the next state we need to move to:<pre>
public function onEnteringState()
{
$game = $this->game;
// Active next player OR end the trick and go to the next trick OR end the hand
if ($game->cards->countCardInLocation('cardsontable') == 4) {
// This is the end of the trick
// Select the winner
$best_value_player_id = $game->activeNextPlayer(); // TODO figure out winner of trick

// Move all cards to "cardswon" of the given player
$game->cards->moveAllCardsInLocation('cardsontable', 'cardswon', null, $best_value_player_id);

if ($game->cards->countCardInLocation('hand') == 0) {
// End of the hand
return EndHand::class;
} else {
// End of the trick
// Reset trick suite to 0
$this->game->setGameStateInitialValue('trick_color', 0);
return PlayerTurn::class;
}
} else {
// Standard case (not the end of the trick)
// => just active the next player
$player_id = $game->activeNextPlayer();
$game->giveExtraTime($player_id);
return PlayerTurn::class;
}
}
</pre>'''Important''': All state actions game or player must return the next state transition (or thrown exception).

==== Player Turn ====
We will not implement this yet, but we can throw an exception to check that the interaction is working properly.
<pre>
#[PossibleAction] // a PHP attribute that tells BGA "this method describes a possible action that the player could take", so that you can call that action from the front (the client)
public function actPlayCard(int $cardId, int $activePlayerId)
{
throw new UserException("Not implemented: $activePlayerId played card $cardId");
return NextPlayer::class; // after the action, we move to the next player
}
</pre>

==Client - Server Interactions==

Now to implement things for real we have hook UI actions to ajax calls, and process notifications sent by the server.
So previously we hooked playCardOnTable right into js handler which caused client animation, in real game its a two
step operation. When user clicks on game element js client sends an ajax call to server, server processes it and updates database, server sends
notification in response, client hooks animations to server notification.

So in .js code replace find out handStock.onCardClick and replace the handler to
<pre>
this.handStock.onCardClick = (card) => {
{
console.log("onCardClick : card ", card);
console.log("onCardClick : namestate ", this.gamedatas.gamestate.name);
if (!card) return; // hmm - should never happen
switch (this.gamedatas.gamestate.name) {
case "PlayerTurn":
// Can play a card
this.bga.actions.performAction("actPlayCard", { cardId: card.id });

break;
case "GiveCards":
// Can give cards TODO
break;
default: {
this.handStock.unselectAll();
break;
}
}
}
};

</pre>

Now reload and when you click on card you should get a server response: Not implemented...

Lets implement it, in '''PlayerTurn.php'''

We need to:

# Move the card
# Notify all player on the the move
<pre>
#[PossibleAction]
public function actPlayCard(int $cardId, int $activePlayerId)
{
$game = $this->game;
$game->cards->moveCard($cardId, 'cardsontable', $activePlayerId);
// TODO: check rules here
$currentCard = $game->cards->getCard($cardId);
// And notify
$game->notify->all('playCard', clienttranslate('${player_name} plays ${value_displayed} ${color_displayed}'), [
'i18n' => array('color_displayed', 'value_displayed'),
'card' => $currentCard,
'player_id' => $activePlayerId,
'player_name' => $game->getActivePlayerName(),
'value_displayed' => $game->card_types['types'][$currentCard['type_arg']]['name'],
'color_displayed' => $game->card_types['suites'][$currentCard['type']]['name']
]
);
return NextPlayer::class;
}
</pre>

We get the card from client, we move it to the table (moveCard is hooked to database directly, its part of deck class),
we notify all players and we change state. What we are missing here is bunch of checks (rule enforcements), we will add it later.

Interesting part about this notify is that we use i18n array for strings that needs to be translated by client, so
they are sent as English text in notification, then client has to know which parameters needs translating.

On the client side .js we have to implement a notification handler to do the animation. Below the '''setupNotification''' method (which you don't need to touch)
after <code>// TODO: from this point and below, you can write your game notifications handling methods</code>

you can put the following code:

<pre>
async notif_newHand(args) {
// We received a new full hand of 13 cards.
this.handStock.removeAll();
this.handStock.addCards(Array.from(Object.values(args.hand)));
}

async notif_playCard(args) {
// Play a card on the table
this.tableauStocks[args.player_id].addCards([args.card]);
}
</pre>

BGA will automatically bind the event to the '''notif_{eventName} handler''' which will receive the "args" you passed from php.

Refresh the page and try to play a card from the correct player. The card should move to the played area. When you refresh - you should still see the card there.
Swicth to next player using the arrows near player name and play next card.
Just before last card save the game state in "Save 1" slot (buttons in the bottom). These saves game states and you can reload it using "Load 1" later.
It is very handy.
Finish playing the trick. You will notice
after trick is done all cards remains on the table, but if you press F5 they would disappear, this is because
we updated database to pick-up the cards but did not send notification about it.

So in '''NextPlayer.php''' file add notification after // Move all cards to "cardswon" of the given player:

<pre>

// Move all win cards to cardswon location
$moved_cards = $game->cards->getCardsInLocation('cardsontable'); // remember for notification what we moved
$game->cards->moveAllCardsInLocation('cardsontable', 'cardswon', null, $best_value_player_id);

// Note: we use 2 notifications here in order we can pause the display during the first notification
// before we move all cards to the winner (during the second)
$players = $game->loadPlayersBasicInfos();
$game->notify->all('trickWin', clienttranslate('${player_name} wins the trick'), array(
'player_id' => $best_value_player_id,
'player_name' => $players[$best_value_player_id]['player_name'],

));

$game->notify->all('giveAllCardsToPlayer', '', array(
'player_id' => $best_value_player_id,
'cards' => $game->cards->getCards(array_keys($moved_cards))
));
</pre>

You notice that we passes player_name in notification because its used in the message but its pretty redundant,
as we should be able to figure out player_name by player_id.

There is a way to fix it.

in constructor of Game.php uncomment the decorator and remove second part that related to cards, so you will end up with
/* notification decorator */

$this->notify->addDecorator(function(string $message, array $args) {
if (isset($args['player_id']) && !isset($args['player_name']) && str_contains($message, '${player_name}')) {
$args['player_name'] = $this->getPlayerNameById($args['player_id']);
}

return $args;
});
Now we can remove player_name as notification argument in NextPlayer.php (and other states) and $players variable because its not used anymore.

$game->notify->all('trickWin', clienttranslate('${player_name} wins the trick'), array(
'player_id' => $best_value_player_id,
));

Now lets add these handlers in the .js file to handle our notifications:
<pre>
async notif_trickWin(args) {
// We do nothing here (just wait in order players can view the 4 cards played before they're gone)
}

async notif_giveAllCardsToPlayer(args) {
// Move all cards on table to given table, then destroy them
const winner_id = args.player_id;
const cards = Array.from(Object.values(args.cards));
await this.tableauStocks[winner_id].addCards(cards);
}
// TODO: cards has to dissapear after
}

</pre>

Ok we notice that cards that was won bunched up in ugly column and stay on tableau, but they should dissaper after trick is taken.

Now lets fix the ugly stock. We can make tableau a bit bigger to fit 4 cards or we should make cards overlap, later makes more sense since making tableau too big will be ugly.

I could not figure out how to do overlap in LineStock, AI thinks that there is attribute cardOverlap that I can set when creatingt stock, but it does not work on LineStock (as on 1.7),
so lets just add css for this in .css file

<pre>
.playertable .ha-card ~ .ha-card {
margin-left: calc(var(--h-card-width) * -0.8);
}
</pre>

This uses tilda operator that target the sibling, which is essentially all cards except first.

If you want to test that it works you can reload you test state using Load 1 button to see the finishing of a trick.

Now reload to test the trick taking - it is pretty now .

Final touch, we need card to dissapear into the void. The void we have to create first.
We need to add another node in the dom for that void stock, on server we called location "cardswon" so lets use same name, change the tableau template in .js file to this<pre>
<div id="tableau_${player.id}"/></div>
<div id="cardswon_${player.id}"/></div>
</pre>

We added cardswon (and class for tableau just in case we need it later).

Now in setup method of .js file we need to create stock for this location, in the loop where we adding tableau stock and the end of loop add this code:
// add void stock
new BgaCards.VoidStock(
this.cardsManager,
document.getElementById(`cardswon_${player.id}`),
{
autoPlace: (card) =>
card.location === "cardswon" && card.location_arg == player.id,
}
);

If you notice we did not assign this to any variable, this is because we won't need to refer to it, we will use autoPlace feature, where cardManager will know where to place it based on the location from server.
Finally we just have to modify notification handler to add this animation, this is final version (in .js file)

notif_giveAllCardsToPlayer: async function (args) {
// Move all cards on table to given table, then destroy them
const winner_id = args.player_id;

const cards = Array.from(Object.values(args.cards));
await this.tableauStocks[winner_id].addCards(cards);
await this.cardsManager.placeCards(cards); // auto-placement
},

So the function is async means it will return Promise. We are doing it so we can wait other animations to complete.
First we adding cards to player tableau, waiting for animation, then adding to our void stock where they are dissapear.

Now after the trick you see all cards move towards the "player's stash".
The animation is not ideal, so lets at void stock settings to see if can improve it: https://x.boardgamearena.net/data/game-libs/bga-cards/1.0.7/docs/classes/stocks_void-stock.VoidStock.html
Ok, well I could not figure it out, but now you know where docs for these components are.
We will do our CSS hack, in .css add:

.cardswon > .ha-card {
position: absolute;
top: 0 !important;
}

==Zombie turn==

We will implement a zombie function now because a) we have to do it at some point
b) playing 13 cards from 4 players manually to test this game is super annoying - but we can actually re-use this feature to "auto-play"

In '''PlayerTurn.php''' file, replace the zombie function with this code:
<pre>
public function zombie(int $playerId)
{
$game = $this->game;
// Auto-play a random card from player's hand
$cards_in_hand = $game->cards->getCardsInLocation('hand', $playerId);
if (count($cards_in_hand) > 0) {
$card_to_play = $cards_in_hand[array_rand($cards_in_hand)];
$game->cards->moveCard($card_to_play['id'], 'cardsontable', $playerId);
// Notify
$game->notify->all(
'playCard',
clienttranslate('${player_name} auto plays ${value_displayed} ${color_displayed}'),
[
'i18n' => array('color_displayed', 'value_displayed'),
'card' => $card_to_play,
'player_id' => $playerId,
'value_displayed' => $game->card_types['types'][$card_to_play['type_arg']]['name'],
'color_displayed' => $game->card_types['suites'][$card_to_play['type']]['name']
]
);
}
return NextPlayer::class;
}
</pre>

Now, watch this! Click Debug symbol on top bar (bug) and select function "playAutomatically" (this is actually function in your php file! it starts with debug_),
and select number of moves, i.e. 4.
If your zombie function works correctly you will see player play automatically. To play whole hand it will be 52 moves (13*4).

==Scoring and End of game handling==

Now we should calculate scoring and for that we need to actually track who wins the trick.
Trick is won by the player with highest card (no trump). We just need to remember what is trick suite.
For which we will use state variable 'trick_color' which we already conveniently created.

In '''PlayerTurn.php''' state, add this before notification
<pre>
$currenttrick_color = $game->getGameStateValue('trick_color');
if ($currenttrick_color == 0) $game->setGameStateValue('trick_color', $currentCard['type']);

</pre>

This will make sure we remember the first suit being played, now we will use it. Modify the '''NextPlayer.php''' state to fix our TODO comment in onEnteringState
<pre>
// Active next player OR end the trick and go to the next trick OR end the hand
if ($game->cards->countCardInLocation('cardsontable') == 4) {
// This is the end of the trick
$cards_on_table = $game->cards->getCardsInLocation('cardsontable');
$best_value = 0;
$best_value_player_id = $this->game->getActivePlayerId(); // fallback
$currenttrick_color = $game->getGameStateValue('trick_color');
foreach ($cards_on_table as $card) {
if ($card['type'] == $currenttrick_color) { // type is card suite
if ($best_value_player_id === null || $card['type_arg'] > $best_value) {
$best_value_player_id = $card['location_arg']; // location_arg is player who played this card on table
$best_value = $card['type_arg']; // type_arg is value of the card (2 to 14)
}
}
}

// Active this player => he's the one who starts the next trick
$this->gamestate->changeActivePlayer($best_value_player_id);

// Move all win cards to cardswon location
$win_location = 'cardswon';
$game->cards->moveAllCardsInLocation('cardsontable', $win_location, null, $best_value_player_id);
// ... notification is the same as before
</pre>

The scoring rule in the studio example code is huge multi-page function, for this tutorial we will make simplier.
Lets score -1 point per heart and call it a day. And game will end when somebody goes -100 or below.

As UI goes for scoring, the main thing to update is:

* The scoring on the mini boards represented by stars
* Show that in the log.

For a real game, you might consider showing the scoring in a [[Game_interface_logic:_yourgamename.js#Scoring_dialogs|Scoring Dialog]] using tableWindow notification, but this is out of scope of this tutorial. You can do that as homework.

In '''EndHand.php''':

<pre>
use Bga\GameFramework\NotificationMessage; // add this to the top of the file, together with the other "use" statements

...

public function onEnteringState()
{
$game = $this->game;
// Count and score points, then end the game or go to the next hand.
$players = $game->loadPlayersBasicInfos();
// Gets all "hearts" + queen of spades

$player_to_points = array();
foreach ($players as $player_id => $player) {
$player_to_points[$player_id] = 0;
}

$cards = $game->cards->getCardsInLocation("cardswon");
foreach ($cards as $card) {
$player_id = $card['location_arg'];
// Note: 2 = heart
if ($card['type'] == 2) {
$player_to_points[$player_id]++;
}
}

// Apply scores to player
foreach ($player_to_points as $player_id => $points) {
if ($points != 0) {
$game->playerScore->inc(
$player_id,
-$points,
new NotificationMessage(
clienttranslate('${player_name} gets ${absInc} hearts and looses ${absInc} points'),
)
);
}
}

///// Test if this is the end of the game
if ($game->playerScore->getMin() <= -100) {
// Trigger the end of the game !
return 99; // end game
}

return NewHand::class;
}
</pre>

The game should work now. Try to play it!
==Clean Up==
We left some code that comes from template and our first code, we should remove it now.

* In .js file remove debugger; statements if any
* Remove debug code from setupNewGame to deal cards, cards are now dealt in stNewHand state handler
// Shuffle deck
$this->cards->shuffle('deck');
// Deal 13 cards to each players
$players = $this->loadPlayersBasicInfos();
foreach ($players as $player_id => $player) {
$this->cards->pickCards(13, 'deck', $player_id);
}
* Find and remove $playerEnergy variable and it's uses from Game.php (was part of template)

==Rule Enforcements==
Now we have a working game, but there is no rule enforcement.
You can implement these rules in the '''actPlayCard''' function of '''PlayerTurn.php'''
<pre>

public function actPlayCard(int $cardId, int $activePlayerId)
{
$game = $this->game;
$card = $game->cards->getCard($cardId);
if (!$card) {
throw new \BgaSystemException("Invalid move");
}
// Rule checks

// Check that player has this card in hand
if ($card['location'] != "hand") {
throw new \BgaUserException(
clienttranslate('You do not have this card in your hand')
);
}
$currenttrick_color = $game->getGameStateValue('trick_color');
// Check that player follows suit if possible
if ($currenttrick_color != 0) {
$has_suit = false;
$hand_cards = $game->cards->getCardsInLocation('hand', $activePlayerId);
foreach ($hand_cards as $hand_card) {
if ($hand_card['type'] == $currenttrick_color) {
$has_suit = true;
break;
}
}
if ($has_suit && $card['type'] != $currenttrick_color) {
throw new \BgaUserException(
clienttranslate('You must follow suit')
);
}
}

</pre>
You can try to play wrong card now and you will see error!
But you noticed we broke the zombie mode as you cannot play random card anymore and now uThe user cannot play ANY card, there are only some cards they can play but we don't show this information which is annoying.
To fix this we can add a helper function that will return a list of playable cards for a given player.
Add these functions in '''Game.php''' file:
<pre>
function getPlayableCards($player_id): array
{
// Get all data needed to check playable cards at the moment
$currentTrickColor = $this->getGameStateValue('trick_color');
$broken_heart = $this->brokenHeart();
$total_played = $this->cards->countCardInLocation('cardswon') + $this->cards->countCardInLocation('cardsontable');
$hand = $this->cards->getPlayerHand($player_id);

$playable_card_ids = [];
$all_ids = array_keys($hand);

if ($this->cards->getCardsInLocation('cardsontable', $player_id)) return []; // Already played a card

// Check whether the first card of the hand has been played or not
// if ($total_played == 0) {
// // No cards have been played yet, find and return the starter card only
// foreach ($hand as $card) if ($card['type'] == 3 && $card['type_arg'] == 2) return [$card['id']]; // 2 of clubs
// return [];
// } else
if (!$currentTrickColor) { // First card of the trick
if ($broken_heart) return $all_ids; // Broken Heart or no limitation, can play any card
else {
// Exclude Heart as Heart hasn't been broken yet
foreach ($hand as $card) if ($card['type'] != 2) $playable_card_ids[] = $card['id'];
if (!$playable_card_ids) return $all_ids; // All Heart cards!
else return $playable_card_ids;
}
} else {
// Must follow the lead suit if possible
$same_suit = false;
foreach ($hand as $card)
if ($card['type'] == $currentTrickColor) {
$same_suit = true;
break;
}
if ($same_suit) return $this->getObjectListFromDB("SELECT card_id FROM card WHERE card_type = $currentTrickColor AND card_location = 'hand' AND card_location_arg = $player_id", true); // Has at least 1 card of the same suit

else return $all_ids;
}
}

function brokenHeart(): bool
{
// Check Heart in the played card piles
return (bool)$this->getUniqueValueFromDB("SELECT count(*) FROM card WHERE card_location = 'cardswon' AND card_type = 2");
}

function tableHeart(): bool
{
// Check Heart in the current trick
return (bool)$this->getUniqueValueFromDB("SELECT count(*) FROM card WHERE card_location = 'cardsontable' AND card_type = 2");
}

</pre>

Now we can use this function in the zombie function of '''PlayerTurn.php''' to pick a random playable card:
<pre>
public function zombie(int $playerId)
{
$playable_cards = $this->game->getPlayableCards($playerId);
$zombieChoice = $this->getRandomZombieChoice($playable_cards); // random choice over possible moves
return $this->actPlayCard((int)$zombieChoice, $playerId);
}
</pre>

And we can significantly simplify our rule check at actPlayCard
<pre>
$game = $this->game;
$currentCard = $game->cards->getCard($cardId);
if (!$currentCard) {
throw new \BgaSystemException("Invalid move");
}
// Rule checks
$playable_cards = $game->getPlayableCards($activePlayerId);
if (!in_array($cardId, $playable_cards)) {
throw new \BgaUserException(clienttranslate("You cannot play this card now"));
}

</pre>
Finally we can send this to the client via state args so the user can see what moves are valid:
In '''PlayerTurn.php''' add this method:
<pre>
public function getArgs(int $activePlayerId): array
{
// Send playable card ids of the active player privately
return [
'_private' => [
$activePlayerId => [
'playableCards' => $this->game->getPlayableCards($activePlayerId)
],
],
];
}
</pre>
On the client side in the .js file replace the onEnteringState method with this code:
<pre>
onEnteringState: function (stateName, args) {
console.log("Entering state: " + stateName, args);
switch (stateName) {
case "PlayerTurn":
if (this.isCurrentPlayerActive()) {
// Check playable cards received from argPlayerTurn() in php

const playableCardIds = args.args._private.playableCards.map((x) =>
parseInt(x)
);

const allCards = this.handStock.getCards();
const playableCards = allCards.filter(
(card) => playableCardIds.includes(parseInt(card.id)) // never know if we get int or string, this method cares
);
this.handStock.setSelectionMode("single", playableCards);
}
break;
}
},
</pre>
And ALSO remove the this.handStock.setSelectionMode("single") line from the setup method. If you leave it there it won't work as this is async function that collide with our other async
functions that we are using in the onEnteringState

==Fix first player with 2 of clubs==

Find the comment
// FIXME: first player one with 2 of clubs
and replace with this code:
// first player one with 2 of clubs
$first_player = $this->game->getUniqueValueFromDb("SELECT card_location_arg FROM card WHERE card_location = 'hand' AND card_type = 3 AND card_type_arg = 2");// 2 of clubs

Then we can uncomment our code for getPlayableCards in Game.php:
//Check whether the first card of the hand has been played or not
$total_played = $this->cards->countCardInLocation('cardswon') + $this->cards->countCardInLocation('cardsontable');
if ($total_played == 0) {
// No cards have been played yet, find and return the starter card only
foreach ($hand as $card) if ($card['type'] == 3 && $card['type_arg'] == 2) return [$card['id']]; // 2 of clubs
return $all_ids; // should not happen
} else

==Spectator support==
A spectator is not a real player but they can watch the game. Most games will require special spectator support, it's one of the steps in the alpha testing checklist.
In this game it's pretty simple, we just hide the hand control in the client

In the .js file in the setup function add this code (after DOM is created):
// Hide hand zone from spectators
if (this.isSpectator)
document.getElementById("myhand_wrap").style.display = "none";

Click Test Spectator at the end of player's panels to test this.

==Improve UI==
We need to fix a few things in the UI still.

===Center Player Areas===
First let's fix the player tables - to make them centered.
In the .css file find #player-tables and change it to this:

#player-tables {
position: relative;
width: calc(var(--h-tableau-width) * 3.8);
height: calc(var(--h-tableau-height) * 2.4);
margin: auto; // that is a cheap way to make it centered
}

===Better Card Play Animations===
When another player plays a card it kind of just appears on the tableau, we want to make it look like it's coming from the player hand.
We don't actually have any sort of UI location to have a player hand - but we can either put it on the mini player panel or add it to the bottom of the player areas.
Let's try to put this on the mini player panels.
First we need to add a node in the DOM on the player panel and maybe add an icon to represent the hand.
We have access to some BGA icons and font awesome icons https://fontawesome.com/v4/icons, so we can pick one from there:

In the .js file in the template for player tableau and add this at the end of the forEach body:
<pre>
document.getElementById(`player_panel_content_${player.color}`).innerHTML =
`<div id="otherhand_${player.id}" class="otherhand"><i class="fa fa-window-restore"></i></div>`;
</pre>
In the .js file replace the notif handler for play with this:
<pre>
notif_playCard: async function (args) {
// Play a card on the table
const playerId = args.player_id;
let settings = {};
if (playerId != this.player_id) {
settings = {
fromElement: $(`otherhand_${playerId}`),
toPlaceholder: "grow",
};
}
await this.tableauStocks[playerId].addCard(args.card, settings);
},
</pre>
What we did here is added a settings parameter for card placement - for cases where it's not our own card to move it from the "hand" area on the mini player board.
Reload and test (use the autoPlay feature to see the animation when the "other" player plays the card).

Now we can also replace the void stock we create with animation to the same "otherhand" area:
<pre>
notif_giveAllCardsToPlayer: async function (args) {
// Move all cards from notification to dedicated player area and fade out
const playerId = args.player_id;

const cards = Array.from(Object.values(args.cards));
await this.tableauStocks[playerId].addCards(cards);
await this.tableauStocks[playerId].removeCards(cards, {
fadeOut: true,
slideTo: $(`otherhand_${playerId}`),
});
},
</pre>
And in this case we don't really need VoidStock anymore, we can remove it
Delete this
<pre>
// add void stock
new BgaCards.VoidStock(
this.cardsManager,
document.getElementById(`cardswon_${playerId}`),
{
fadeOut: true, // not working
toPlaceholder: "shrink", // not working
autoPlace: (card) =>
card.location === "cardswon" && card.location_arg == playerId,
}
);
</pre>
Also can delete related css and DOM element cardswon.

We can also add this in .css to make this symbol centered:
.otherhand {
position: relative;
margin: auto;
text-align: center;
}

===Card Sorting===
It would be nice to sort the cards in hand by suit and value.
You can add sorting
// create the stock, in the game setup
this.handStock = new BgaCards.HandStock(
this.cardsManager,
document.getElementById("myhand"),
{
sort: BgaCards.sort('type', 'type_arg'), // sort by suite then by value
}
);

but you will notice its not sorted right.
Its because of type mismatch. The server sends us strings and bga-cards expects integers.
We have to change this on client or server. I was already doing some ugly convertion on client, so lets just make it official.
We will add 2 functions in utility section that will do the convertions for us:
///////////////////////////////////////////////////
//// Utility methods

remapToBgaCardList: function (cards) {
if (!cards) return [];
if (cards.type) {
// actually one card
return [this.remapToBgaCard(cards)];
} else if (Array.isArray(cards)) {
return cards.map((card) => this.remapToBgaCard(card));
} else {
return Object.values(cards).map((card) => this.remapToBgaCard(card));
}
},
remapToBgaCard: function (card) {
// proper casts
return {
id: parseInt(card.id),
type: parseInt(card.type),
type_arg: parseInt(card.type_arg),
location: card.location,
location_arg: parseInt(card.location_arg),
};
},
Then in setup change addCards to this
this.handStock.addCards(this.remapToBgaCardList(this.gamedatas.hand));
and
// Cards played on table
for (i in this.gamedatas.cardsontable) {
var card = this.gamedatas.cardsontable[i];
var player_id = card.location_arg;
this.tableauStocks[player_id].addCard(this.remapToBgaCard(card));
}

In notif_newHand replace addCards like this:
this.handStock.addCards(this.remapToBgaCardList(args.hand));

In notif_giveAllCardsToPlayer
const cards = this.remapToBgaCardList(args.cards);
In notif_playCard
await this.tableauStocks[playerId].addCard(this.remapToBgaCard(args.card), settings);

Now sorting should work!

===Tooltips===
We can add tooltips to cards to show their name.
In the .js file find where created silly tooltip with addTooltipHtml and replace with this:
this.bga.gameui.addTooltipHtml(div.id,
_(this.gamedatas.card_types.types[card.type_arg].name)+ " " +
_(this.gamedatas.card_types.suites[card.type].name)
);
Now what is this.gamedatas.card_types? Well that is our "material" of the game which is in our case variable in php, we have to send it to client for this to work.
Since it never changes we send it in getAllDatas method, add this at the end before return:
$result['card_types'] = $this->card_types;

Of course this is very basic tooltips and not even needed in this game, but in real game your want tooltips everywhere!!!
Lets add tooltip to our fake hand symbol also (the "otherhand") (in setup method in .js somewhere in forEach loop over players)
// add tooltips to player hand symbol
this.bga.gameui.addTooltipHtml(
`otherhand_${playerId}`,
_("Placeholder for player's hand")
);

==Game progresstion==
In this game it should be easy, we just need to know if somebody close to -100 points!
Find getGameProgression in Game.php and replace with this:
public function getGameProgression()
{
$min = $this->playerScore->getMin();
return -1 * $min; // we get close to -100 we get close to 100% game completion
}

==Additional stuff==

The following things were not implemented and you can add them yourself by looking at the code of the original hearts game:

*Mark player who started the hand and add log about what is starting Suite of the trick
*Start scoring with 100 points each and end when <= 0
*Fix scoring rules with Q of spades and 26 point reverse scoring
*Add statistics
*Add card exchange states
*Add game option to start with 75 points instead of 100

==After the tutorial==
You might want to check another tutorial, or start working on your first real project!

[[Create a game in BGA Studio: Complete Walkthrough]]
[[Category:Studio]]

File:HeartsTutorialImage1.png

2026-03-16T20:56:47Z

RichardSPeters:

screen shot of hearts tutorial