Board Game Arena - User contributions [en]

Using Typescript and Scss

2025-10-07T00:14:40Z

ShaharHarshuv: /* Typescript file skeleton */

This page will help you set up your project to use Typescript client file and Scss style files, and automatically build Javascript (in ES5) files and CSS files so your project stay compatible to BGA framework requirements.
You can use only TS or only SCSS part if you want, they are not linked.

The following document is geared towards setting up a custom project where you will be in charge of typing all components that you want to use.
There is also untested 3rd party project that aims to automate some of the steps below, you can look at this instead [[BGA Type Safe Template]].

== Install and configure ==

=== Install dev stack ===
Install node/npm. Here is an example to activate auto-build in Visual Studio Code, if you use another tool I strongly recommend to find an equivalent so you don't have to launch build manually after each modification.

=== Configure package.json and tsconfig.json ===

Create a file named <code>package.json</code> on the root folder, not on the src folder.

'''package.json'''

{
"name": "yourgamename",
"version": "1.0.0",
"description": "",
"main": "YourGameName.js",
"scripts": {
"build:ts": "tsc",
"build:scss": "sass --no-source-map src/yourgamename.scss yourgamename.css",
"watch:ts": "tsc --watch",
"watch:scss": "sass --watch src/yourgamename.scss yourgamename.css",
"watch": "npm run watch:ts && npm run watch:scss",
"build": "npm run build:ts && npm run build:scss"
},
"author": "yourname",
"license": "MIT",
"devDependencies": {
"sass": "^1.32.6",
"typescript": "^4.1.3"
}
}

Note: if you not using scss - remove corresponding scripts and deps.

When package.json is created, run <code>npm i</code> on the root folder to install builders (will generate a node_modules folder).

IMPORTANT: exclude node_modules/ subfolder from auto-sync to remote folder (whatever system you use for that).

For Typescript compilation we also need to set up a <code>tsconfig.json</code> on the root folder.

'''tsconfig.json'''

{
"rootDir": ".",
"compilerOptions": {
"target": "es5",
"module": "none",
"lib": ["dom", "esnext"],
"sourceMap": false,
"typeRoots": ["src/types", "./types", "./node_modules/@types"],
"outFile": "YourGameName.js"
},
"files": [
"bga-framework.d.ts",
"src/yourgamename.d.ts",
"src/yourgamename.ts",
"src/define.ts"
]
}

Note: it only works now with es5

If you want to split your code onto multiple files, just add them in the file list (order is important for dependencies, new subpart should go on top of the list). No need to import classes or types from one file to another. In fact, you can't with this configuration.

== Create skeleton ==
When you create your game in BGA Studio, a JS and CSS file are generated. As we will overwrite them with autobuild. You can put the TS/SCSS files on a <code>src</code> folder to separate them from built files, but that's not mandatory.
Note to myself: check if 'src' dir will be svn version control, if not cannot really use it (even if duplicated in git).

Note: if you're using SFTP and have "bga-framework.d.ts" in the ignore list - remove it and resync. You will need this file.

=== Typescript file skeleton ===
Typescript example here have been stripped down of all comments for clarity.
Your TS code can be splitted in multiple files, you can have a look at [https://studio.boardgamearena.com/projects castlecombo] code for inspiration.
To make this page concise, I removed comments and code samples. If it's your first game, well - don't do it if your first game - you won't be able to apply other code samples from docs, they all using dojo style and have to completely rewritten.

'''src/yourgamename.d.ts'''

<pre>
interface YourGameNamePlayer extends Player {
cards: Card[]; // any information you add on each result['players']
}

interface YourGameNameGamedatas extends Gamedatas<YourGameNamePlayer> {
// Add here variables you set up in getAllDatas
discardedCards: { [row: number]: Card[] };
remainingCardsInDecks: { [row: number]: number };
tableCards: { [row: number]: Card[] };
}
</pre>
Not: the Generic typing is optional.

'''src/yourgamename.ts'''

<pre>
// @ts-ignore
GameGui = (function () { // this hack required so we fake extend GameGui
function GameGui() {}
return GameGui;
})();

// Note: it does not really extend it in es6 way, you cannot call super you have to use dojo way
class YourGameName extends GameGui<YourGameNameGamedatas> {
constructor() {}

public setup(gamedatas: any) {
this.setupNotifications();
}
public onEnteringState(stateName: string, args: any) {}
public onLeavingState(stateName: string) {}
public onUpdateActionButtons(stateName: string, args: any) {}
public setupNotifications() {}
}
</pre>

To plug the class with BGA framework, we'll also create another file:

'''src/define.ts'''

define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/stock"
],
function (dojo, declare) {
return declare("bgagame.yourgamename", ebg.core.gamegui, new YourGameName());
});
Copy <code>bgagame.yourgamename</code> from original JS to avoid name mistakes with letter case.

Don't forget to sync the bga-framework.d.ts from your FTP folder regularly to get the last version.

=== SCSS file ===
Nothing special here, just write classic SCSS (will be compiled by Dart scss) and name it '''src/yourgamename.scss'''.

Example:
<pre>
@use 'variables' as v;

/* the other files */
@use "./Animations";
@use "./Board";

#ebd-body {
background-image: url(img/woodbg.jpg);
background-repeat: repeat;
}
@each $key, $val in v.$colors-list {
.fgcolor#{$key} {
color: #{$val};
}

</pre>

Your SCSS code can be (should be) splitted in multiple files, for example:

'''variables.scss'''
<pre>
$colors-list: (
_6cd0f6: #6cd0f6, // blue
_ef58a2: #ef58a2, // pink
_ffcc02: #ffcc02, // yellow
_a0d28c: #a0d28c // green
);
</pre>

== Auto build and auto upload ==

=== Auto build JS and CSS files ===

To build and watch (i.e. re-build continuously changed files) run in terminal:
npm run watch

Alternately you can make vscode to do it for you by installing Run on Save extension, see details in [[Setting_up_BGA_Development_environment_using_VSCode]]

Note: to build without watch
npm run build

=== Auto-upload generated files ===
You can setup standard file sync or use vscode SFTP extension, see details in [[Setting_up_BGA_Development_environment_using_VSCode]]

Make sure that your sftp.json file has a "watcher" section to detect and upload changes made outside of the VSCode IDE.

<pre>
"watcher": {
"files": "**/*.{js,css}",
"autoUpload": true,
"autoDelete": true
}
</pre>

=== Exclusions from auto-upload ===
Make sure <code>.vscode</code> and <code>node_modules</code> are in <code>.gitignore</code> if you commit your project somewhere.

=== Code completion ===
To have a code completion for framework classes, dojo, stock, etc, you'll need to make sure bga-framework.d.ts file is added to your tsconfig.

== Using the new libs ==
To use the new front libs (bga-autofit, bga-score-sheet, ...), you will need to add a little trick as the game class is not declared inside the define function.
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
getLibUrl('bga-score-sheet', '1.0.0'),
],
function (dojo, declare, gamegui, counter, BgaScoreSheet) {
(window as any).BgaScoreSheet = BgaScoreSheet; // add this to make the variable accessible from anywhere
return declare("bgagame.castlecombo", ebg.core.gamegui, new CastleCombo());
});
When you will call <code>this.scoreSheet = new BgaScoreSheet.ScoreSheet(...)</code>, as it will be inside the Game class setup, the added line will be already executed and <code>BgaScoreSheet</code> will be available globally.

To add the lib typing to your project, follow the [[BgaScoreSheet#Using%20with%20TypeScript|Using with TypeScript]] section of the corresponding lib.

== Referenced Projects ==

* https://github.com/thoun/bga-ts-example
* https://github.com/elaskavaia/bga-dojoless
* https://github.com/NevinAF/bga-ts-template

[[Category:Studio]]

Tutorial hearts

2025-10-05T22:24:02Z

ShaharHarshuv: /* Scoring and End of game handling */

{{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]]).
* Know the rules for Hearts
* 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]

== 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. 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.
</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 full game can be found in your FTP home folder, after getting read-only access: https://en.doc.boardgamearena.com/First_steps_with_BGA_Studio#Set_up_dev_environment_ide,_editor_and_File_Sync

== 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://github.com/elaskavaia/bga-heartsla/blob/4b3a73eeb5acae961ade18473af119e8ce8d1a8f/img/cards.jpg hearts img/cards.jpg] into img/ folder of your project.
<blockquote>There are better quality deck of cards image at https://en.doc.boardgamearena.com/Common_board_game_elements_image_resources</blockquote>

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>
document.getElementById('game_play_area').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 (the image slightly obsolete, you may see more stuff there and different prompt).

[[File:Heartsla-tpl2.png]]

Now lets add a card into the hand, just so you can feel it. Edit the html string we inserted earlier and a playertablecard div inside a hand div
<pre>
...
<div id="myhand">
<div class="playertablecard"></div>
</div>
...
</pre>

Edit .css file
<pre>
.playertablecard {
display: inline-block;
position: relative;
margin-top: 5px;
width: 72px;
height: 96px;
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:

[[File:Heartsla-tpl3.png]]

Awesome! Now lets do the rest of layout.

Note: If you don't see the card a) check it was synced to remote folder b) force reload page

Let's complete the template string we created for the hand. You template should have this code, just leave it there
<pre>

// Example to add a div on the game area
document.getElementById("game_play_area").insertAdjacentHTML("beforeend",
`
<div id="player-tables"></div>
`
);
</pre>

Then change the following template code to this
<pre>
// Setting up player boards
var numPlayers = Object.keys(gamedatas.players).length;
Object.values(gamedatas.players).forEach((player, index) => {
document.getElementById("player-tables").insertAdjacentHTML(
"beforeend",
`
<div class="playertable whiteblock playertable_${DIRECTIONS[numPlayers][index]}">
<div class="playertablename" style="color:#${player.color};"><span class="dealer_token" id="dealer_token_p${player.id}">🃏 </span>${player.name}</div>
<div class="playertablecard" id="playertablecard_${player.id}"></div>
<div class="playertablename" id="hand_score_wrap_${player.id}"><span class="hand_score_label"></span> <span id="hand_score_${player.id}"></span></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
heartslav.js:68 Uncaught (in promise) ReferenceError: DIRECTIONS is not defined

For this new code to work, we need to add a constant at the beginning of the JS file, defining the expected position of each player (right after copyright comment):
<pre>
const DIRECTIONS = {
3: ['S', 'W', 'E'],
4: ['S', 'W', 'N', 'E'],
};
</pre>

Reload. If everything went well you should see this:

[[File:Hearts all rows.png|alt=Display a list of all players, with a dummy card in each position]]

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>
/** Table layout **/

#player-tables {
position: relative;
width: 710px;
height: 340px;
}

.playertablename {
font-weight: bold;
}

.playertable {
position: absolute;
text-align: center;
width: 180px;
height: 130px;
}

.playertable_N {
left: 50%;
top: 0px;
margin-left: -90px; /* half of 180 */
}
.playertable_S {
left: 50%;
bottom: 0px;
margin-left: -90px; /* half of 180 */
}
.playertable_W {
left: 0px;
top: 50%;
margin-top: -55px; /* half of 130 */
}
.playertable_E {
right: 0px;
top: 50%;
margin-top: -55px; /* half of 130 */
}
</pre>

Now you force Reload and you should see this:
[[File:Heartsla-tpl5.png]]

This is almost all we need for graphics and layout, there are few tweaks left there but lets do some more heavy lifting now.

<i>Note: if you did not see changes you may have not force reloaded, force means you use Ctrl+F5 or Cltr+Shift-R, if you don't "force" browser will use cached version of images! Which is not what you just changed</i>

<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 JS Stock ==

The BGA framework provides a few out of the box classes to deal with cards. The client side
contains a class called [[Stock]] and it can be used for any dynamic html "pieces" management that uses
common sprite images. 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 13x4 grid of images stitched together,
which is a very efficient way to transport images. So we will use the Stock class to mark up these images and create
"card" divs for us.

First, we need to add '''ebg/stock''' as a dependency in the .js file:
<pre>
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/stock" /// <==== HERE, don't forget comma before
],
</pre>

Then add this to the Javascript constructor, this will define size of our cards
<pre>
console.log('hearts constructor');
this.cardwidth = 72;
this.cardheight = 96;
</pre>

The stock is initialized in the Javascript "setup" method, after we have created the "myhand" element", like this:
<pre>
// TODO: Set up your game interface here, according to "gamedatas"

// Player hand
this.playerHand = new ebg.stock(); // new stock object for hand
this.playerHand.create( this, $('myhand'), this.cardwidth, this.cardheight );
</pre>

As parameters of the "create" method, we provided the width/height of an item (a card), and the container div "myhand" - which is an id of "div" element we have created before.

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

Here's how we tell stock what item types to display (add after .create):
<pre>
this.playerHand.image_items_per_row = 13; // 13 images per row

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

And add this function to the utilities section
<pre>
// Get card unique identifier based on its color and value
getCardUniqueId : function(color, value) {
return (color - 1) * 13 + (value - 2);
},
</pre>

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

Note: we need to generate a unique ID for each type of card based on its color and value. For that we create a function '''getCardUniqueId'''. The type is the unique identifier of the TYPE of the card, e.g., the queen of spades encoded as an integer. If our deck had 2 standard card decks we would have had 2 queens of spades; they would share the same type and the same image but would have different ids. NOTE: It's unfortunate that they named this '''getCardUniqueId'''; it should have been '''getCardUniqueType''', because it really isn't an id, but a TYPE of card. The type of the item should either be a reversible function of its properties (i.e., kind of suite * 13 + value) or just an enumerator described in material.inc.php. In this specific case it's a synthetic type id, which also the same as the number of the card in the sprite image (i.e., if you enumerate each image in sprite going left to right, then top to bottom).

Now let's add the 5 of Hearts to the player's hand just for fun (this code will go in setup method after types initialization):

<pre>
// 2 = hearts, 5 is 5, and 42 is the card id, which normally would come from db
this.playerHand.addToStockWithId( this.getCardUniqueId( 2, 5 ), 42 );
</pre>

This will add the card with id 42 and type 16 ( (2-1)*13+(5-2)=16 ).

Note that number 16 would not be something you can see in database, Deck database will have separate field for type and type_arg where type is suite and type_arg is number, so its not the same thing, but you can use same formula to convert. Number 42 on the other hand would be id field in database. But we get to database in the later section.

If you reload now you should see the 5 of hearts in "your hand".

You may see some weird graphics glitches - its because we did not remove our hack with background from .css yet. You can go to .css file now and remove line with comment "temp hack to see it".

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, after this.playerHand is initialised:

dojo.connect( this.playerHand, 'onChangeSelection', this, 'onPlayerHandSelectionChanged' );

Then find the Player's action comment section in .js file and add a handler after the comment:

<pre>
///////////////////////////////////////////////////
//// Player's action

onPlayerHandSelectionChanged: function () {
var items = this.playerHand.getSelectedItems();

if (items.length > 0) {
if (this.checkAction("actPlayCard", true)) {
// Can play a card

var card_id = items[0].id;
console.log("on playCard " + card_id);

this.playerHand.unselectAll();
} else if (this.checkAction("actGiveCards")) {
// Can give cards => let the player select some cards
} else {
this.playerHand.unselectAll();
}
}
},
</pre>

''Note : If you already have an example handler <code>onCardClick: function( card_id )</code>, go ahead and remove that handler, it is a duplicate of what we are implementing in this tutorial and may cause issues later on.''

The function name of the handler is 4th parameter of the dojo.connect function. Make sure you spell it correctly or there will be unpredictable effects.

Now if you reload, open the Javascript Console (F12), and then click on the card in My Hand, you should see:
on playCard 42
printed on the console

''Note : You need to be the active player to have rights to play a card and so log your message in the console''

== 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 ====
To modify the schema, first exit your existing game(s). Open '''dbmodel.sql''' file and uncomment the card table creation.

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

This is the "card" table which will be managed by the Deck php class.

In addition we want a little piece of information in the players table:

-- add info about first player
ALTER TABLE `player` ADD `player_first` BOOLEAN NOT NULL DEFAULT '0';

Not sure why they put this into the player table, as we could use a global db variable to hold first player as easily.
But I am just following the existing code more-or-less. It is not recommended to modify player table in general.

=== Game State Variables ===
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>
parent::__construct();
$this->initGameStateLabels(
[
"currentHandType" => 10,
"trickColor" => 11,
"alreadyPlayedHearts" => 12,
]
);;

$this->cards = $this->deckFactory->createDeck('card');
</pre>

If you see errors in IDE its because we also have to declared "cards" as class member, add ''public $cards;'' before the contructor.

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:

*"trickColor": numbers from 1 to 4 that map to card suit (not sure why it's called color; maybe it's a translation from French);
*"alreadyPlayedHearts": a boolean flag (0 or 1) indicating whether somebody used hearts on the trick;
*"currentHandType": stores the value to indicate who to give cards to during exchange.

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>

Since we changed the db, 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>

Code Rev [https://github.com/elaskavaia/bga-heartsla/tree/acd1926a6c09dc9afd0752cb6b78eef17c5dfe5c]

=== 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 "TODO: Setup the initial game situation here" comment.
<pre>
// Init global values with their initial values

// Note: hand types: 0 = give 3 cards to player on the left
// 1 = give 3 cards to player on the right
// 2 = give 3 cards to player opposite
// 3 = keep cards
$this->setGameStateInitialValue('currentHandType', 0);

// Set current trick color to zero (= no trick color)
$this->setGameStateInitialValue('trickColor', 0);

// Mark if we already played hearts during this hand
$this->setGameStateInitialValue('alreadyPlayedHearts', 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.
<pre>
// Create cards
$cards = [];
foreach (self::$CARD_SUITS as $suit => $suit_info) {
// spade, heart, diamond, club
foreach (self::$CARD_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 ''self:$CARD_SUITS''.
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 (if you already have ''self::$CARD_TYPES'', replace it)

<pre>
elf::$CARD_SUITS = [
1 => [
'name' => clienttranslate('Spade'),
],
2 => [
'name' => clienttranslate('Heart'),
],
3 => [
'name' => clienttranslate('Club'),
],
4 => [
'name' => clienttranslate('Diamond'),
]
];

self::$CARD_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 declared these fields in the class
public static array $CARD_SUITS;
public static array $CARD_TYPES;

==== 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) {
$cards = $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', $current_player_id);

// 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 .js file in the setup function (which is the receiver of getAllDatas) replace our hack of putting 5 of Hearts directly into the hand with:

<pre>
// Cards in player's hand
for (var i in this.gamedatas.hand) {
var card = this.gamedatas.hand[i];
var color = card.type;
var value = card.type_arg;
this.playerHand.addToStockWithId(this.getCardUniqueId(color, value), card.id);
}
</pre>

At this point, you could start a new game and each player should see their hand!

=== Cards on Table ===
To the setup method, add:
// Cards played on table
for (i in this.gamedatas.cardsontable) {
var card = this.gamedatas.cardsontable[i];
var color = card.type;
var value = card.type_arg;
var player_id = card.location_arg;
this.playCardOnTable(player_id, color, value, card.id);
}
Add the '''playCardOnTable''' function in the "utilities" section.

<pre>
playCardOnTable : function(player_id, color, value, card_id) {
// player_id => direction
this.addTableCard(value, color, player_id, player_id);

if (player_id != this.player_id) {
// Some opponent played a card
// Move card from player panel
this.placeOnObject('cardontable_' + player_id, 'overall_player_board_' + player_id);
} else {
// You played a card. If it exists in your hand, move card from there and remove
// corresponding item

if ($('myhand_item_' + card_id)) {
this.placeOnObject('cardontable_' + player_id, 'myhand_item_' + card_id);
this.playerHand.removeFromStockById(card_id);
}
}

// In any case: move it to its final destination
this.slideToObject('cardontable_' + player_id, 'playertablecard_' + player_id).play();
},
</pre>

For this to work we also need to define the addTableCard
<pre>
addTableCard(value, color, card_player_id, playerTableId) {
const x = value - 2;
const y = color - 1;
document.getElementById('playertablecard_' + playerTableId).insertAdjacentHTML('beforeend', `
<div class="card cardontable" id="cardontable_${card_player_id}" style="background-position:-${x}00% -${y}00%"></div>
`);
},
</pre>

What this does is basically create another card object, because if it is not our card it's not in our hand (Stock) so
we have to create it out of thin air. Now we have an object with an id of 'cardontable_' + player_id. Depending
on who is playing it we either place it on the player miniboard or in hand (and remove it from hand stock). Then we animate the card move.

We also should fix our .css file now to add style for cardontable and REMOVE background for playertablecard which really is a placeholder div and not a card. (Don't miss the remove step; it will be all screwy if you do!)

<pre>
.playertablecard {
display: inline-block;
position: relative;
margin-top: 5px;
width: 72px;
height: 96px;
/* we remove background-image here */
}

/*** cards on table ***/

.cardontable {
position: absolute;
width: 72px;
height: 96px;
background-image: url('img/cards.jpg');
}
</pre>

Next, we will hook-up clicking on card and test if our ''playCardOnTable'' works.

Find ''onPlayerHandSelectionChanged'' function in the JS file, we should have logging there like ''console.log("on playCard "+card_id);''
So after that insert this (Note: this code is for testing we will replace it with server interaction after we test it.):
<pre>
console.log("on playCard " + card_id);
// type is (color - 1) * 13 + (value - 2)
var type = items[0].type;
var color = Math.floor(type / 13) + 1;
var value = (type % 13) + 2;

this.playCardOnTable(this.player_id, color, value, card_id);
</pre>
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]]

Code Rev [https://github.com/elaskavaia/bga-heartsla/tree/0ed80e254a6d0c29f267b308d1c2016db90fd4f6]

==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. 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 is selected who will start a new trick ("NewTrick")
*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) ("NextHand")

=== Creating the basic states ===
Let's create our first state - "NewHand". Create a new file under "module/php/State" (you can delete the existing files there) and name it "'''NewHand.php'''".
<pre>
<?php

namespace Bga\Games\Heartsclay\States;

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

class NewHand extends \Bga\GameFramework\States\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
description: "",
updateGameProgression: true, // entering this state can update the progress bar of the game
);
}

// The action we do when entering the state
public function onEnteringState()
{
// TODO: implement logic
return NewTrick::class;
}
}

</pre>
You can read more about it here: [[State classes: State directory]]

Let's implement the other states:

==== '''NewTrick.php''' ====
<pre>
<?php

namespace Bga\Games\Heartsclay\States;

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

class NewTrick extends \Bga\GameFramework\States\GameState
{
public function __construct(protected Game $game)
{
parent::__construct(
$game,
id: 30,
type: StateType::GAME,
description: "",
);
}

public function onEnteringState()
{
// TODO: implement logic
return PlayerTurn::class;
}
}

</pre>

==== '''PlayerTurn.php''' ====
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

namespace Bga\Games\Heartsclay\States;

use Bga\GameFramework\StateType;
use Bga\Games\Heartsclay\Game;
use Bga\GameFramework\States\PossibleAction;

class PlayerTurn extends \Bga\GameFramework\States\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): void
{
// 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 \BgaUserException('Not implemented: zombie for player ${player_id}', args: [
'player_id' => $playerId,
]);
}
}

</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 not implement this as part of a tutorial. Feel free to go back to it if you want to complete the game.

==== '''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 '''NewTrick'''
* If this is the last trick (no more cards in end) and it's finished, we need to go to '''EndHand'''

For now, let's return '''PlayerTurn'''. We'll implement the logic later.<pre>
<?php

namespace Bga\Games\Heartsclay\States;

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

class NextPlayer extends \Bga\GameFramework\States\GameState
{
public function __construct(protected Game $game)
{
parent::__construct(
$game,
id: 32,
type: StateType::GAME,
description: "",
);
}

public function onEnteringState(): int
{
return PlayerTurn::class;
}
}

</pre>

==== '''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'''.

<pre>
<?php

namespace Bga\Games\Heartsclay\States;

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

class EndHand extends \Bga\GameFramework\States\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>

==== State Logic ====

===== New Hand =====
We need to:

# Move all cards to the deck
# Shuffle the cards
# Deal the cards to the players
# Reset the "alreadyPlayedHearts" state

Here's the code:<pre>
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->notify->player($player_id, 'newHand', '', array('cards' => $cards));
}
$game->setGameStateValue('alreadyPlayedHearts', 0);
return NewTrick::class;
}
</pre>

===== New Trick =====
We only need to reset the trick color<pre>
public function onEnteringState()
{
// New trick: active the player who wins the last trick, or the player who own the club-2 card
// Reset trick color to 0 (= no color)
$this->game->setGameStateInitialValue('trickColor', 0);
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
// Move all cards to "cardswon" of the given player
$best_value_player_id = $game->activeNextPlayer(); // TODO figure out winner of trick
$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
return NewTrick::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 Action =====
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 \BgaUserException('Not implemented: ${player_id} played card ${card_id}', args: [
'player_id' => $activePlayerId,
'card_id' => $cardId,
]);
return NextPlayer::class; // after the action, we move to the next player
}
</pre>

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

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<pre>
onUpdateActionButtons: function (stateName, args) {
console.log("onUpdateActionButtons: " + stateName, args);

if (this.isCurrentPlayerActive()) {
switch (stateName) {
case "playerTurn":
break;
}
}
},
</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 '''onPlayerHandSelectionChanged''' with
<pre>
onPlayerHandSelectionChanged : function() {
var items = this.playerHand.getSelectedItems();

if (items.length > 0) {
var action = 'actPlayCard';
if (this.checkAction(action, true)) {
// Can play a card
const cardId = items[0].id;
this.bgaPerformAction(action, {
cardId, // this corresponds to the argument name in php, so it needs to be exactly the same
});

this.playerHand.unselectAll();
} else if (this.checkAction('actGiveCards')) {
// Can give cards => let the player select some cards
} else {
this.playerHand.unselectAll();
}
}
},
</pre>

Now 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}'), array(
'i18n' => array('color_displayed', 'value_displayed'),
'card_id' => $cardId,
'player_id' => $activePlayerId,
'player_name' => $game->getActivePlayerName(),
'value' => $currentCard['type_arg'],
'value_displayed' => Game::$CARD_TYPES[$currentCard['type_arg']]['name'],
'color' => $currentCard['type'],
'color_displayed' => Game::$CARD_SUITS[$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) you can put the following code:

<pre>
notif_newHand: function (notif) {
// We received a new full hand of 13 cards.
this.playerHand.removeAll();

for (var i in notif.cards) {
var card = notif.cards[i];
var color = card.type;
var value = card.type_arg;
this.playerHand.addToStockWithId(
this.getCardUniqueId(color, value),
card.id,
);
}
},

notif_playCard: function (notif) {
// Play a card on the table
this.playCardOnTable(
notif.player_id,
notif.color,
notif.value,
notif.card_id,
);
},
</pre>

BGA will automatically bind the event to the '''notif_{eventName} handler.'''

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.

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

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

And add these handlers in the .js file:<pre>
notif_trickWin: function (notif) {
// We do nothing here (just wait in order players can view the 4 cards played before they're gone.
},
notif_giveAllCardsToPlayer: function (notif) {
// Move all cards on table to given table, then destroy them
var winner_id = notif.player_id;
for (var player_id in this.gamedatas.players) {
var anim = this.slideToObject(
"cardontable_" + player_id,
"overall_player_board_" + winner_id,
);
dojo.connect(anim, "onEnd", function (node) {
dojo.destroy(node);
});
anim.play();
}
},
</pre>

'''<u>Editor note</u>: after migrating the examples to up to date practices I couldn't figure out how you're supposed to do the delay. So the bottom part might not make sense. This part in the guide should be updated.'''

So 'trickWin' notification does not do much except it will delay the processing of next notification by 1 second (1000 ms)
and it will log the message (that happens independently of what handler does).
<i>Note: if on the other hand you don't want to log but want to do something else, send an empty message</i>

Now after the trick you see all cards move towards the "player's stash".

==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 'trickColor' which we already conveniently created.

In '''PlayerTurn.php''' state, add this before any notification
<pre>
$currentTrickColor = $game->getGameStateValue('trickColor');
if ($currentTrickColor == 0) $game->setGameStateValue('trickColor', $currentCard['type']);

</pre>

This will make sure we remember the first suit being played, now to use it modify the '''NextPlayer.php''' state to fix our TODO comment
<pre>
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 = null;
$currentTrickColor = $game->getGameStateValue('trickColor');
foreach ($cards_on_table as $card) {
// Note: type = card color
if ($card['type'] == $currentTrickColor) {
if ($best_value_player_id === null || $card['type_arg'] > $best_value) {
$best_value_player_id = $card['location_arg']; // Note: location_arg = player who played this card on table
$best_value = $card['type_arg']; // Note: type_arg = value of the card
}
}
}

// Active this player => he's the one who starts the next trick
$this->gamestate->changeActivePlayer($best_value_player_id);

// Move all cards to "cardswon" of the given player
$game->cards->moveAllCardsInLocation('cardsontable', 'cardswon', null, $best_value_player_id);

// Notify
// ... same code 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!

==Additional stuff==

The following things were not implemented and can add them yourself by looking at the code of original hearts game:

*Remove debug code from setupNewGame to deal cards, cards are now dealt in stNewHand state handler
*Rule checking and rule enforcements in actPlayCard function
*Start scoring with 100 points each and end when <= 0
*Fix scoring rules with Q of spades and 26 point reverse scoring
*First player one with 2 club
*Add progress handling
*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

2025-10-05T22:09:34Z

ShaharHarshuv: /* Client - Server Interactions */

{{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]]).
* Know the rules for Hearts
* 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]

== 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. 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.
</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 full game can be found in your FTP home folder, after getting read-only access: https://en.doc.boardgamearena.com/First_steps_with_BGA_Studio#Set_up_dev_environment_ide,_editor_and_File_Sync

== 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://github.com/elaskavaia/bga-heartsla/blob/4b3a73eeb5acae961ade18473af119e8ce8d1a8f/img/cards.jpg hearts img/cards.jpg] into img/ folder of your project.
<blockquote>There are better quality deck of cards image at https://en.doc.boardgamearena.com/Common_board_game_elements_image_resources</blockquote>

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>
document.getElementById('game_play_area').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 (the image slightly obsolete, you may see more stuff there and different prompt).

[[File:Heartsla-tpl2.png]]

Now lets add a card into the hand, just so you can feel it. Edit the html string we inserted earlier and a playertablecard div inside a hand div
<pre>
...
<div id="myhand">
<div class="playertablecard"></div>
</div>
...
</pre>

Edit .css file
<pre>
.playertablecard {
display: inline-block;
position: relative;
margin-top: 5px;
width: 72px;
height: 96px;
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:

[[File:Heartsla-tpl3.png]]

Awesome! Now lets do the rest of layout.

Note: If you don't see the card a) check it was synced to remote folder b) force reload page

Let's complete the template string we created for the hand. You template should have this code, just leave it there
<pre>

// Example to add a div on the game area
document.getElementById("game_play_area").insertAdjacentHTML("beforeend",
`
<div id="player-tables"></div>
`
);
</pre>

Then change the following template code to this
<pre>
// Setting up player boards
var numPlayers = Object.keys(gamedatas.players).length;
Object.values(gamedatas.players).forEach((player, index) => {
document.getElementById("player-tables").insertAdjacentHTML(
"beforeend",
`
<div class="playertable whiteblock playertable_${DIRECTIONS[numPlayers][index]}">
<div class="playertablename" style="color:#${player.color};"><span class="dealer_token" id="dealer_token_p${player.id}">🃏 </span>${player.name}</div>
<div class="playertablecard" id="playertablecard_${player.id}"></div>
<div class="playertablename" id="hand_score_wrap_${player.id}"><span class="hand_score_label"></span> <span id="hand_score_${player.id}"></span></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
heartslav.js:68 Uncaught (in promise) ReferenceError: DIRECTIONS is not defined

For this new code to work, we need to add a constant at the beginning of the JS file, defining the expected position of each player (right after copyright comment):
<pre>
const DIRECTIONS = {
3: ['S', 'W', 'E'],
4: ['S', 'W', 'N', 'E'],
};
</pre>

Reload. If everything went well you should see this:

[[File:Hearts all rows.png|alt=Display a list of all players, with a dummy card in each position]]

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>
/** Table layout **/

#player-tables {
position: relative;
width: 710px;
height: 340px;
}

.playertablename {
font-weight: bold;
}

.playertable {
position: absolute;
text-align: center;
width: 180px;
height: 130px;
}

.playertable_N {
left: 50%;
top: 0px;
margin-left: -90px; /* half of 180 */
}
.playertable_S {
left: 50%;
bottom: 0px;
margin-left: -90px; /* half of 180 */
}
.playertable_W {
left: 0px;
top: 50%;
margin-top: -55px; /* half of 130 */
}
.playertable_E {
right: 0px;
top: 50%;
margin-top: -55px; /* half of 130 */
}
</pre>

Now you force Reload and you should see this:
[[File:Heartsla-tpl5.png]]

This is almost all we need for graphics and layout, there are few tweaks left there but lets do some more heavy lifting now.

<i>Note: if you did not see changes you may have not force reloaded, force means you use Ctrl+F5 or Cltr+Shift-R, if you don't "force" browser will use cached version of images! Which is not what you just changed</i>

<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 JS Stock ==

The BGA framework provides a few out of the box classes to deal with cards. The client side
contains a class called [[Stock]] and it can be used for any dynamic html "pieces" management that uses
common sprite images. 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 13x4 grid of images stitched together,
which is a very efficient way to transport images. So we will use the Stock class to mark up these images and create
"card" divs for us.

First, we need to add '''ebg/stock''' as a dependency in the .js file:
<pre>
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/stock" /// <==== HERE, don't forget comma before
],
</pre>

Then add this to the Javascript constructor, this will define size of our cards
<pre>
console.log('hearts constructor');
this.cardwidth = 72;
this.cardheight = 96;
</pre>

The stock is initialized in the Javascript "setup" method, after we have created the "myhand" element", like this:
<pre>
// TODO: Set up your game interface here, according to "gamedatas"

// Player hand
this.playerHand = new ebg.stock(); // new stock object for hand
this.playerHand.create( this, $('myhand'), this.cardwidth, this.cardheight );
</pre>

As parameters of the "create" method, we provided the width/height of an item (a card), and the container div "myhand" - which is an id of "div" element we have created before.

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

Here's how we tell stock what item types to display (add after .create):
<pre>
this.playerHand.image_items_per_row = 13; // 13 images per row

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

And add this function to the utilities section
<pre>
// Get card unique identifier based on its color and value
getCardUniqueId : function(color, value) {
return (color - 1) * 13 + (value - 2);
},
</pre>

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

Note: we need to generate a unique ID for each type of card based on its color and value. For that we create a function '''getCardUniqueId'''. The type is the unique identifier of the TYPE of the card, e.g., the queen of spades encoded as an integer. If our deck had 2 standard card decks we would have had 2 queens of spades; they would share the same type and the same image but would have different ids. NOTE: It's unfortunate that they named this '''getCardUniqueId'''; it should have been '''getCardUniqueType''', because it really isn't an id, but a TYPE of card. The type of the item should either be a reversible function of its properties (i.e., kind of suite * 13 + value) or just an enumerator described in material.inc.php. In this specific case it's a synthetic type id, which also the same as the number of the card in the sprite image (i.e., if you enumerate each image in sprite going left to right, then top to bottom).

Now let's add the 5 of Hearts to the player's hand just for fun (this code will go in setup method after types initialization):

<pre>
// 2 = hearts, 5 is 5, and 42 is the card id, which normally would come from db
this.playerHand.addToStockWithId( this.getCardUniqueId( 2, 5 ), 42 );
</pre>

This will add the card with id 42 and type 16 ( (2-1)*13+(5-2)=16 ).

Note that number 16 would not be something you can see in database, Deck database will have separate field for type and type_arg where type is suite and type_arg is number, so its not the same thing, but you can use same formula to convert. Number 42 on the other hand would be id field in database. But we get to database in the later section.

If you reload now you should see the 5 of hearts in "your hand".

You may see some weird graphics glitches - its because we did not remove our hack with background from .css yet. You can go to .css file now and remove line with comment "temp hack to see it".

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, after this.playerHand is initialised:

dojo.connect( this.playerHand, 'onChangeSelection', this, 'onPlayerHandSelectionChanged' );

Then find the Player's action comment section in .js file and add a handler after the comment:

<pre>
///////////////////////////////////////////////////
//// Player's action

onPlayerHandSelectionChanged: function () {
var items = this.playerHand.getSelectedItems();

if (items.length > 0) {
if (this.checkAction("actPlayCard", true)) {
// Can play a card

var card_id = items[0].id;
console.log("on playCard " + card_id);

this.playerHand.unselectAll();
} else if (this.checkAction("actGiveCards")) {
// Can give cards => let the player select some cards
} else {
this.playerHand.unselectAll();
}
}
},
</pre>

''Note : If you already have an example handler <code>onCardClick: function( card_id )</code>, go ahead and remove that handler, it is a duplicate of what we are implementing in this tutorial and may cause issues later on.''

The function name of the handler is 4th parameter of the dojo.connect function. Make sure you spell it correctly or there will be unpredictable effects.

Now if you reload, open the Javascript Console (F12), and then click on the card in My Hand, you should see:
on playCard 42
printed on the console

''Note : You need to be the active player to have rights to play a card and so log your message in the console''

== 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 ====
To modify the schema, first exit your existing game(s). Open '''dbmodel.sql''' file and uncomment the card table creation.

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

This is the "card" table which will be managed by the Deck php class.

In addition we want a little piece of information in the players table:

-- add info about first player
ALTER TABLE `player` ADD `player_first` BOOLEAN NOT NULL DEFAULT '0';

Not sure why they put this into the player table, as we could use a global db variable to hold first player as easily.
But I am just following the existing code more-or-less. It is not recommended to modify player table in general.

=== Game State Variables ===
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>
parent::__construct();
$this->initGameStateLabels(
[
"currentHandType" => 10,
"trickColor" => 11,
"alreadyPlayedHearts" => 12,
]
);;

$this->cards = $this->deckFactory->createDeck('card');
</pre>

If you see errors in IDE its because we also have to declared "cards" as class member, add ''public $cards;'' before the contructor.

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:

*"trickColor": numbers from 1 to 4 that map to card suit (not sure why it's called color; maybe it's a translation from French);
*"alreadyPlayedHearts": a boolean flag (0 or 1) indicating whether somebody used hearts on the trick;
*"currentHandType": stores the value to indicate who to give cards to during exchange.

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>

Since we changed the db, 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>

Code Rev [https://github.com/elaskavaia/bga-heartsla/tree/acd1926a6c09dc9afd0752cb6b78eef17c5dfe5c]

=== 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 "TODO: Setup the initial game situation here" comment.
<pre>
// Init global values with their initial values

// Note: hand types: 0 = give 3 cards to player on the left
// 1 = give 3 cards to player on the right
// 2 = give 3 cards to player opposite
// 3 = keep cards
$this->setGameStateInitialValue('currentHandType', 0);

// Set current trick color to zero (= no trick color)
$this->setGameStateInitialValue('trickColor', 0);

// Mark if we already played hearts during this hand
$this->setGameStateInitialValue('alreadyPlayedHearts', 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.
<pre>
// Create cards
$cards = [];
foreach (self::$CARD_SUITS as $suit => $suit_info) {
// spade, heart, diamond, club
foreach (self::$CARD_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 ''self:$CARD_SUITS''.
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 (if you already have ''self::$CARD_TYPES'', replace it)

<pre>
elf::$CARD_SUITS = [
1 => [
'name' => clienttranslate('Spade'),
],
2 => [
'name' => clienttranslate('Heart'),
],
3 => [
'name' => clienttranslate('Club'),
],
4 => [
'name' => clienttranslate('Diamond'),
]
];

self::$CARD_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 declared these fields in the class
public static array $CARD_SUITS;
public static array $CARD_TYPES;

==== 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) {
$cards = $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', $current_player_id);

// 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 .js file in the setup function (which is the receiver of getAllDatas) replace our hack of putting 5 of Hearts directly into the hand with:

<pre>
// Cards in player's hand
for (var i in this.gamedatas.hand) {
var card = this.gamedatas.hand[i];
var color = card.type;
var value = card.type_arg;
this.playerHand.addToStockWithId(this.getCardUniqueId(color, value), card.id);
}
</pre>

At this point, you could start a new game and each player should see their hand!

=== Cards on Table ===
To the setup method, add:
// Cards played on table
for (i in this.gamedatas.cardsontable) {
var card = this.gamedatas.cardsontable[i];
var color = card.type;
var value = card.type_arg;
var player_id = card.location_arg;
this.playCardOnTable(player_id, color, value, card.id);
}
Add the '''playCardOnTable''' function in the "utilities" section.

<pre>
playCardOnTable : function(player_id, color, value, card_id) {
// player_id => direction
this.addTableCard(value, color, player_id, player_id);

if (player_id != this.player_id) {
// Some opponent played a card
// Move card from player panel
this.placeOnObject('cardontable_' + player_id, 'overall_player_board_' + player_id);
} else {
// You played a card. If it exists in your hand, move card from there and remove
// corresponding item

if ($('myhand_item_' + card_id)) {
this.placeOnObject('cardontable_' + player_id, 'myhand_item_' + card_id);
this.playerHand.removeFromStockById(card_id);
}
}

// In any case: move it to its final destination
this.slideToObject('cardontable_' + player_id, 'playertablecard_' + player_id).play();
},
</pre>

For this to work we also need to define the addTableCard
<pre>
addTableCard(value, color, card_player_id, playerTableId) {
const x = value - 2;
const y = color - 1;
document.getElementById('playertablecard_' + playerTableId).insertAdjacentHTML('beforeend', `
<div class="card cardontable" id="cardontable_${card_player_id}" style="background-position:-${x}00% -${y}00%"></div>
`);
},
</pre>

What this does is basically create another card object, because if it is not our card it's not in our hand (Stock) so
we have to create it out of thin air. Now we have an object with an id of 'cardontable_' + player_id. Depending
on who is playing it we either place it on the player miniboard or in hand (and remove it from hand stock). Then we animate the card move.

We also should fix our .css file now to add style for cardontable and REMOVE background for playertablecard which really is a placeholder div and not a card. (Don't miss the remove step; it will be all screwy if you do!)

<pre>
.playertablecard {
display: inline-block;
position: relative;
margin-top: 5px;
width: 72px;
height: 96px;
/* we remove background-image here */
}

/*** cards on table ***/

.cardontable {
position: absolute;
width: 72px;
height: 96px;
background-image: url('img/cards.jpg');
}
</pre>

Next, we will hook-up clicking on card and test if our ''playCardOnTable'' works.

Find ''onPlayerHandSelectionChanged'' function in the JS file, we should have logging there like ''console.log("on playCard "+card_id);''
So after that insert this (Note: this code is for testing we will replace it with server interaction after we test it.):
<pre>
console.log("on playCard " + card_id);
// type is (color - 1) * 13 + (value - 2)
var type = items[0].type;
var color = Math.floor(type / 13) + 1;
var value = (type % 13) + 2;

this.playCardOnTable(this.player_id, color, value, card_id);
</pre>
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]]

Code Rev [https://github.com/elaskavaia/bga-heartsla/tree/0ed80e254a6d0c29f267b308d1c2016db90fd4f6]

==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. 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 is selected who will start a new trick ("NewTrick")
*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) ("NextHand")

=== Creating the basic states ===
Let's create our first state - "NewHand". Create a new file under "module/php/State" (you can delete the existing files there) and name it "'''NewHand.php'''".
<pre>
<?php

namespace Bga\Games\Heartsclay\States;

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

class NewHand extends \Bga\GameFramework\States\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
description: "",
updateGameProgression: true, // entering this state can update the progress bar of the game
);
}

// The action we do when entering the state
public function onEnteringState()
{
// TODO: implement logic
return NewTrick::class;
}
}

</pre>
You can read more about it here: [[State classes: State directory]]

Let's implement the other states:

==== '''NewTrick.php''' ====
<pre>
<?php

namespace Bga\Games\Heartsclay\States;

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

class NewTrick extends \Bga\GameFramework\States\GameState
{
public function __construct(protected Game $game)
{
parent::__construct(
$game,
id: 30,
type: StateType::GAME,
description: "",
);
}

public function onEnteringState()
{
// TODO: implement logic
return PlayerTurn::class;
}
}

</pre>

==== '''PlayerTurn.php''' ====
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

namespace Bga\Games\Heartsclay\States;

use Bga\GameFramework\StateType;
use Bga\Games\Heartsclay\Game;
use Bga\GameFramework\States\PossibleAction;

class PlayerTurn extends \Bga\GameFramework\States\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): void
{
// 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 \BgaUserException('Not implemented: zombie for player ${player_id}', args: [
'player_id' => $playerId,
]);
}
}

</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 not implement this as part of a tutorial. Feel free to go back to it if you want to complete the game.

==== '''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 '''NewTrick'''
* If this is the last trick (no more cards in end) and it's finished, we need to go to '''EndHand'''

For now, let's return '''PlayerTurn'''. We'll implement the logic later.<pre>
<?php

namespace Bga\Games\Heartsclay\States;

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

class NextPlayer extends \Bga\GameFramework\States\GameState
{
public function __construct(protected Game $game)
{
parent::__construct(
$game,
id: 32,
type: StateType::GAME,
description: "",
);
}

public function onEnteringState(): int
{
return PlayerTurn::class;
}
}

</pre>

==== '''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'''.

<pre>
<?php

namespace Bga\Games\Heartsclay\States;

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

class EndHand extends \Bga\GameFramework\States\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>

==== State Logic ====

===== New Hand =====
We need to:

# Move all cards to the deck
# Shuffle the cards
# Deal the cards to the players
# Reset the "alreadyPlayedHearts" state

Here's the code:<pre>
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->notify->player($player_id, 'newHand', '', array('cards' => $cards));
}
$game->setGameStateValue('alreadyPlayedHearts', 0);
return NewTrick::class;
}
</pre>

===== New Trick =====
We only need to reset the trick color<pre>
public function onEnteringState()
{
// New trick: active the player who wins the last trick, or the player who own the club-2 card
// Reset trick color to 0 (= no color)
$this->game->setGameStateInitialValue('trickColor', 0);
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
// Move all cards to "cardswon" of the given player
$best_value_player_id = $game->activeNextPlayer(); // TODO figure out winner of trick
$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
return NewTrick::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 Action =====
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 \BgaUserException('Not implemented: ${player_id} played card ${card_id}', args: [
'player_id' => $activePlayerId,
'card_id' => $cardId,
]);
return NextPlayer::class; // after the action, we move to the next player
}
</pre>

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

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<pre>
onUpdateActionButtons: function (stateName, args) {
console.log("onUpdateActionButtons: " + stateName, args);

if (this.isCurrentPlayerActive()) {
switch (stateName) {
case "playerTurn":
break;
}
}
},
</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 '''onPlayerHandSelectionChanged''' with
<pre>
onPlayerHandSelectionChanged : function() {
var items = this.playerHand.getSelectedItems();

if (items.length > 0) {
var action = 'actPlayCard';
if (this.checkAction(action, true)) {
// Can play a card
const cardId = items[0].id;
this.bgaPerformAction(action, {
cardId, // this corresponds to the argument name in php, so it needs to be exactly the same
});

this.playerHand.unselectAll();
} else if (this.checkAction('actGiveCards')) {
// Can give cards => let the player select some cards
} else {
this.playerHand.unselectAll();
}
}
},
</pre>

Now 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}'), array(
'i18n' => array('color_displayed', 'value_displayed'),
'card_id' => $cardId,
'player_id' => $activePlayerId,
'player_name' => $game->getActivePlayerName(),
'value' => $currentCard['type_arg'],
'value_displayed' => Game::$CARD_TYPES[$currentCard['type_arg']]['name'],
'color' => $currentCard['type'],
'color_displayed' => Game::$CARD_SUITS[$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) you can put the following code:

<pre>
notif_newHand: function (notif) {
// We received a new full hand of 13 cards.
this.playerHand.removeAll();

for (var i in notif.cards) {
var card = notif.cards[i];
var color = card.type;
var value = card.type_arg;
this.playerHand.addToStockWithId(
this.getCardUniqueId(color, value),
card.id,
);
}
},

notif_playCard: function (notif) {
// Play a card on the table
this.playCardOnTable(
notif.player_id,
notif.color,
notif.value,
notif.card_id,
);
},
</pre>

BGA will automatically bind the event to the '''notif_{eventName} handler.'''

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.

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

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

And add these handlers in the .js file:<pre>
notif_trickWin: function (notif) {
// We do nothing here (just wait in order players can view the 4 cards played before they're gone.
},
notif_giveAllCardsToPlayer: function (notif) {
// Move all cards on table to given table, then destroy them
var winner_id = notif.player_id;
for (var player_id in this.gamedatas.players) {
var anim = this.slideToObject(
"cardontable_" + player_id,
"overall_player_board_" + winner_id,
);
dojo.connect(anim, "onEnd", function (node) {
dojo.destroy(node);
});
anim.play();
}
},
</pre>

'''<u>Editor note</u>: after migrating the examples to up to date practices I couldn't figure out how you're supposed to do the delay. So the bottom part might not make sense. This part in the guide should be updated.'''

So 'trickWin' notification does not do much except it will delay the processing of next notification by 1 second (1000 ms)
and it will log the message (that happens independently of what handler does).
<i>Note: if on the other hand you don't want to log but want to do something else, send an empty message</i>

Now after the trick you see all cards move towards the "player's stash".

==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 'trickColor' which we already conveniently created.

In Game.php file find the actPlayCard function and add this before notify functions
$currentTrickColor = $this->getGameStateValue( 'trickColor' ) ;
if( $currentTrickColor == 0 )
$this->setGameStateValue( 'trickColor', $currentCard['type'] );

This will make sure we remember the first suit being played, now to use it modify the stNextPlayer function to fix our TODO comment
<pre>
function stNextPlayer() {
// Active next player OR end the trick and go to the next trick OR end the hand
if ($this->cards->countCardInLocation('cardsontable') == 4) {
// This is the end of the trick
$cards_on_table = $this->cards->getCardsInLocation('cardsontable');
$best_value = 0;
$best_value_player_id = null;
$currentTrickColor = $this->getGameStateValue('trickColor');
foreach ( $cards_on_table as $card ) {
// Note: type = card color
if ($card ['type'] == $currentTrickColor) {
if ($best_value_player_id === null || $card ['type_arg'] > $best_value) {
$best_value_player_id = $card ['location_arg']; // Note: location_arg = player who played this card on table
$best_value = $card ['type_arg']; // Note: type_arg = value of the card
}
}
}

// Active this player => he's the one who starts the next trick
$this->gamestate->changeActivePlayer( $best_value_player_id );

// Move all cards to "cardswon" of the given player
$this->cards->moveAllCardsInLocation('cardsontable', 'cardswon', null, $best_value_player_id);

// Notify
// ... same code here 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, also
we want to show that in the log.
In addition scoring can be shown in [[Game_interface_logic:_yourgamename.js#Scoring_dialogs|Scoring Dialog]] using tableWindow notification, but it is a tutorial on its own and you can do it as homework (it is part of original heart game).

so in Game.php our stEndHand function will look like

<pre>
function stEndHand() {
// Count and score points, then end the game or go to the next hand.
$players = $this->loadPlayersBasicInfos();
// Gets all "hearts" + queen of spades

$player_to_points = array ();
foreach ( $players as $player_id => $player ) {
$player_to_points [$player_id] = 0;
}
$cards = $this->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) {
$this->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 ($this->playerScore->getMin() <= -100) {
// Trigger the end of the game !
$this->gamestate->nextState("endGame");
return;
}

$this->gamestate->nextState("nextHand");
}
</pre>

So it should more less work now, including end of game condition. Try to play it!

==Additional stuff==

The following things were not implemented and can add them yourself by looking at the code of original hearts game:

*Remove debug code from setupNewGame to deal cards, cards are now dealt in stNewHand state handler
*Rule checking and rule enforcements in actPlayCard function
*Start scoring with 100 points each and end when <= 0
*Fix scoring rules with Q of spades and 26 point reverse scoring
*First player one with 2 club
*Add progress handling
*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

2025-10-05T20:52:57Z

ShaharHarshuv: /* Client - Server interactions */

{{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]]).
* Know the rules for Hearts
* 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]

== 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. 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.
</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 full game can be found in your FTP home folder, after getting read-only access: https://en.doc.boardgamearena.com/First_steps_with_BGA_Studio#Set_up_dev_environment_ide,_editor_and_File_Sync

== 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://github.com/elaskavaia/bga-heartsla/blob/4b3a73eeb5acae961ade18473af119e8ce8d1a8f/img/cards.jpg hearts img/cards.jpg] into img/ folder of your project.
<blockquote>There are better quality deck of cards image at https://en.doc.boardgamearena.com/Common_board_game_elements_image_resources</blockquote>

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>
document.getElementById('game_play_area').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 (the image slightly obsolete, you may see more stuff there and different prompt).

[[File:Heartsla-tpl2.png]]

Now lets add a card into the hand, just so you can feel it. Edit the html string we inserted earlier and a playertablecard div inside a hand div
<pre>
...
<div id="myhand">
<div class="playertablecard"></div>
</div>
...
</pre>

Edit .css file
<pre>
.playertablecard {
display: inline-block;
position: relative;
margin-top: 5px;
width: 72px;
height: 96px;
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:

[[File:Heartsla-tpl3.png]]

Awesome! Now lets do the rest of layout.

Note: If you don't see the card a) check it was synced to remote folder b) force reload page

Let's complete the template string we created for the hand. You template should have this code, just leave it there
<pre>

// Example to add a div on the game area
document.getElementById("game_play_area").insertAdjacentHTML("beforeend",
`
<div id="player-tables"></div>
`
);
</pre>

Then change the following template code to this
<pre>
// Setting up player boards
var numPlayers = Object.keys(gamedatas.players).length;
Object.values(gamedatas.players).forEach((player, index) => {
document.getElementById("player-tables").insertAdjacentHTML(
"beforeend",
`
<div class="playertable whiteblock playertable_${DIRECTIONS[numPlayers][index]}">
<div class="playertablename" style="color:#${player.color};"><span class="dealer_token" id="dealer_token_p${player.id}">🃏 </span>${player.name}</div>
<div class="playertablecard" id="playertablecard_${player.id}"></div>
<div class="playertablename" id="hand_score_wrap_${player.id}"><span class="hand_score_label"></span> <span id="hand_score_${player.id}"></span></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
heartslav.js:68 Uncaught (in promise) ReferenceError: DIRECTIONS is not defined

For this new code to work, we need to add a constant at the beginning of the JS file, defining the expected position of each player (right after copyright comment):
<pre>
const DIRECTIONS = {
3: ['S', 'W', 'E'],
4: ['S', 'W', 'N', 'E'],
};
</pre>

Reload. If everything went well you should see this:

[[File:Hearts all rows.png|alt=Display a list of all players, with a dummy card in each position]]

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>
/** Table layout **/

#player-tables {
position: relative;
width: 710px;
height: 340px;
}

.playertablename {
font-weight: bold;
}

.playertable {
position: absolute;
text-align: center;
width: 180px;
height: 130px;
}

.playertable_N {
left: 50%;
top: 0px;
margin-left: -90px; /* half of 180 */
}
.playertable_S {
left: 50%;
bottom: 0px;
margin-left: -90px; /* half of 180 */
}
.playertable_W {
left: 0px;
top: 50%;
margin-top: -55px; /* half of 130 */
}
.playertable_E {
right: 0px;
top: 50%;
margin-top: -55px; /* half of 130 */
}
</pre>

Now you force Reload and you should see this:
[[File:Heartsla-tpl5.png]]

This is almost all we need for graphics and layout, there are few tweaks left there but lets do some more heavy lifting now.

<i>Note: if you did not see changes you may have not force reloaded, force means you use Ctrl+F5 or Cltr+Shift-R, if you don't "force" browser will use cached version of images! Which is not what you just changed</i>

<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 JS Stock ==

The BGA framework provides a few out of the box classes to deal with cards. The client side
contains a class called [[Stock]] and it can be used for any dynamic html "pieces" management that uses
common sprite images. 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 13x4 grid of images stitched together,
which is a very efficient way to transport images. So we will use the Stock class to mark up these images and create
"card" divs for us.

First, we need to add '''ebg/stock''' as a dependency in the .js file:
<pre>
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/stock" /// <==== HERE, don't forget comma before
],
</pre>

Then add this to the Javascript constructor, this will define size of our cards
<pre>
console.log('hearts constructor');
this.cardwidth = 72;
this.cardheight = 96;
</pre>

The stock is initialized in the Javascript "setup" method, after we have created the "myhand" element", like this:
<pre>
// TODO: Set up your game interface here, according to "gamedatas"

// Player hand
this.playerHand = new ebg.stock(); // new stock object for hand
this.playerHand.create( this, $('myhand'), this.cardwidth, this.cardheight );
</pre>

As parameters of the "create" method, we provided the width/height of an item (a card), and the container div "myhand" - which is an id of "div" element we have created before.

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

Here's how we tell stock what item types to display (add after .create):
<pre>
this.playerHand.image_items_per_row = 13; // 13 images per row

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

And add this function to the utilities section
<pre>
// Get card unique identifier based on its color and value
getCardUniqueId : function(color, value) {
return (color - 1) * 13 + (value - 2);
},
</pre>

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

Note: we need to generate a unique ID for each type of card based on its color and value. For that we create a function '''getCardUniqueId'''. The type is the unique identifier of the TYPE of the card, e.g., the queen of spades encoded as an integer. If our deck had 2 standard card decks we would have had 2 queens of spades; they would share the same type and the same image but would have different ids. NOTE: It's unfortunate that they named this '''getCardUniqueId'''; it should have been '''getCardUniqueType''', because it really isn't an id, but a TYPE of card. The type of the item should either be a reversible function of its properties (i.e., kind of suite * 13 + value) or just an enumerator described in material.inc.php. In this specific case it's a synthetic type id, which also the same as the number of the card in the sprite image (i.e., if you enumerate each image in sprite going left to right, then top to bottom).

Now let's add the 5 of Hearts to the player's hand just for fun (this code will go in setup method after types initialization):

<pre>
// 2 = hearts, 5 is 5, and 42 is the card id, which normally would come from db
this.playerHand.addToStockWithId( this.getCardUniqueId( 2, 5 ), 42 );
</pre>

This will add the card with id 42 and type 16 ( (2-1)*13+(5-2)=16 ).

Note that number 16 would not be something you can see in database, Deck database will have separate field for type and type_arg where type is suite and type_arg is number, so its not the same thing, but you can use same formula to convert. Number 42 on the other hand would be id field in database. But we get to database in the later section.

If you reload now you should see the 5 of hearts in "your hand".

You may see some weird graphics glitches - its because we did not remove our hack with background from .css yet. You can go to .css file now and remove line with comment "temp hack to see it".

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, after this.playerHand is initialised:

dojo.connect( this.playerHand, 'onChangeSelection', this, 'onPlayerHandSelectionChanged' );

Then find the Player's action comment section in .js file and add a handler after the comment:

<pre>
///////////////////////////////////////////////////
//// Player's action

onPlayerHandSelectionChanged: function () {
var items = this.playerHand.getSelectedItems();

if (items.length > 0) {
if (this.checkAction("actPlayCard", true)) {
// Can play a card

var card_id = items[0].id;
console.log("on playCard " + card_id);

this.playerHand.unselectAll();
} else if (this.checkAction("actGiveCards")) {
// Can give cards => let the player select some cards
} else {
this.playerHand.unselectAll();
}
}
},
</pre>

''Note : If you already have an example handler <code>onCardClick: function( card_id )</code>, go ahead and remove that handler, it is a duplicate of what we are implementing in this tutorial and may cause issues later on.''

The function name of the handler is 4th parameter of the dojo.connect function. Make sure you spell it correctly or there will be unpredictable effects.

Now if you reload, open the Javascript Console (F12), and then click on the card in My Hand, you should see:
on playCard 42
printed on the console

''Note : You need to be the active player to have rights to play a card and so log your message in the console''

== 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 ====
To modify the schema, first exit your existing game(s). Open '''dbmodel.sql''' file and uncomment the card table creation.

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

This is the "card" table which will be managed by the Deck php class.

In addition we want a little piece of information in the players table:

-- add info about first player
ALTER TABLE `player` ADD `player_first` BOOLEAN NOT NULL DEFAULT '0';

Not sure why they put this into the player table, as we could use a global db variable to hold first player as easily.
But I am just following the existing code more-or-less. It is not recommended to modify player table in general.

=== Game State Variables ===
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>
parent::__construct();
$this->initGameStateLabels(
[
"currentHandType" => 10,
"trickColor" => 11,
"alreadyPlayedHearts" => 12,
]
);;

$this->cards = $this->deckFactory->createDeck('card');
</pre>

If you see errors in IDE its because we also have to declared "cards" as class member, add ''public $cards;'' before the contructor.

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:

*"trickColor": numbers from 1 to 4 that map to card suit (not sure why it's called color; maybe it's a translation from French);
*"alreadyPlayedHearts": a boolean flag (0 or 1) indicating whether somebody used hearts on the trick;
*"currentHandType": stores the value to indicate who to give cards to during exchange.

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>

Since we changed the db, 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>

Code Rev [https://github.com/elaskavaia/bga-heartsla/tree/acd1926a6c09dc9afd0752cb6b78eef17c5dfe5c]

=== 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 "TODO: Setup the initial game situation here" comment.
<pre>
// Init global values with their initial values

// Note: hand types: 0 = give 3 cards to player on the left
// 1 = give 3 cards to player on the right
// 2 = give 3 cards to player opposite
// 3 = keep cards
$this->setGameStateInitialValue('currentHandType', 0);

// Set current trick color to zero (= no trick color)
$this->setGameStateInitialValue('trickColor', 0);

// Mark if we already played hearts during this hand
$this->setGameStateInitialValue('alreadyPlayedHearts', 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.
<pre>
// Create cards
$cards = [];
foreach (self::$CARD_SUITS as $suit => $suit_info) {
// spade, heart, diamond, club
foreach (self::$CARD_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 ''self:$CARD_SUITS''.
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 (if you already have ''self::$CARD_TYPES'', replace it)

<pre>
elf::$CARD_SUITS = [
1 => [
'name' => clienttranslate('Spade'),
],
2 => [
'name' => clienttranslate('Heart'),
],
3 => [
'name' => clienttranslate('Club'),
],
4 => [
'name' => clienttranslate('Diamond'),
]
];

self::$CARD_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 declared these fields in the class
private static array $CARD_SUITS;
private static array $CARD_TYPES;

==== 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) {
$cards = $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', $current_player_id);

// 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 .js file in the setup function (which is the receiver of getAllDatas) replace our hack of putting 5 of Hearts directly into the hand with:

<pre>
// Cards in player's hand
for (var i in this.gamedatas.hand) {
var card = this.gamedatas.hand[i];
var color = card.type;
var value = card.type_arg;
this.playerHand.addToStockWithId(this.getCardUniqueId(color, value), card.id);
}
</pre>

At this point, you could start a new game and each player should see their hand!

=== Cards on Table ===
To the setup method, add:
// Cards played on table
for (i in this.gamedatas.cardsontable) {
var card = this.gamedatas.cardsontable[i];
var color = card.type;
var value = card.type_arg;
var player_id = card.location_arg;
this.playCardOnTable(player_id, color, value, card.id);
}
Add the '''playCardOnTable''' function in the "utilities" section.

<pre>
playCardOnTable : function(player_id, color, value, card_id) {
// player_id => direction
this.addTableCard(value, color, player_id, player_id);

if (player_id != this.player_id) {
// Some opponent played a card
// Move card from player panel
this.placeOnObject('cardontable_' + player_id, 'overall_player_board_' + player_id);
} else {
// You played a card. If it exists in your hand, move card from there and remove
// corresponding item

if ($('myhand_item_' + card_id)) {
this.placeOnObject('cardontable_' + player_id, 'myhand_item_' + card_id);
this.playerHand.removeFromStockById(card_id);
}
}

// In any case: move it to its final destination
this.slideToObject('cardontable_' + player_id, 'playertablecard_' + player_id).play();
},
</pre>

For this to work we also need to define the addTableCard
<pre>
addTableCard(value, color, card_player_id, playerTableId) {
const x = value - 2;
const y = color - 1;
document.getElementById('playertablecard_' + playerTableId).insertAdjacentHTML('beforeend', `
<div class="card cardontable" id="cardontable_${card_player_id}" style="background-position:-${x}00% -${y}00%"></div>
`);
},
</pre>

What this does is basically create another card object, because if it is not our card it's not in our hand (Stock) so
we have to create it out of thin air. Now we have an object with an id of 'cardontable_' + player_id. Depending
on who is playing it we either place it on the player miniboard or in hand (and remove it from hand stock). Then we animate the card move.

We also should fix our .css file now to add style for cardontable and REMOVE background for playertablecard which really is a placeholder div and not a card. (Don't miss the remove step; it will be all screwy if you do!)

<pre>
.playertablecard {
display: inline-block;
position: relative;
margin-top: 5px;
width: 72px;
height: 96px;
/* we remove background-image here */
}

/*** cards on table ***/

.cardontable {
position: absolute;
width: 72px;
height: 96px;
background-image: url('img/cards.jpg');
}
</pre>

Next, we will hook-up clicking on card and test if our ''playCardOnTable'' works.

Find ''onPlayerHandSelectionChanged'' function in the JS file, we should have logging there like ''console.log("on playCard "+card_id);''
So after that insert this (Note: this code is for testing we will replace it with server interaction after we test it.):
<pre>
console.log("on playCard " + card_id);
// type is (color - 1) * 13 + (value - 2)
var type = items[0].type;
var color = Math.floor(type / 13) + 1;
var value = (type % 13) + 2;

this.playCardOnTable(this.player_id, color, value, card_id);
</pre>
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]]

Code Rev [https://github.com/elaskavaia/bga-heartsla/tree/0ed80e254a6d0c29f267b308d1c2016db90fd4f6]

==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. 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 is selected who will start a new trick ("NewTrick")
*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) ("NextHand")

=== Creating the basic states ===
Let's create our first state - "NewHand". Create a new file under "module/php/State" (you can delete the existing files there) and name it "'''NewHand.php'''".
<pre>
<?php

namespace Bga\Games\Heartsclay\States;

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

class NewHand extends \Bga\GameFramework\States\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
description: "",
updateGameProgression: true, // entering this state can update the progress bar of the game
);
}

// The action we do when entering the state
public function onEnteringState()
{
// TODO: implement logic
return NewTrick::class;
}
}

</pre>
You can read more about it here: [[State classes: State directory]]

Let's implement the other states:

==== '''NewTrick.php''' ====
<pre>
<?php

namespace Bga\Games\Heartsclay\States;

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

class NewTrick extends \Bga\GameFramework\States\GameState
{
public function __construct(protected Game $game)
{
parent::__construct(
$game,
id: 30,
type: StateType::GAME,
description: "",
);
}

public function onEnteringState()
{
// TODO: implement logic
return PlayerTurn::class;
}
}

</pre>

==== '''PlayerTurn.php''' ====
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

namespace Bga\Games\Heartsclay\States;

use Bga\GameFramework\StateType;
use Bga\Games\Heartsclay\Game;
use Bga\GameFramework\States\PossibleAction;

class PlayerTurn extends \Bga\GameFramework\States\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): void
{
// 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 \BgaUserException('Not implemented: zombie for player ${player_id}', args: [
'player_id' => $playerId,
]);
}
}

</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 not implement this as part of a tutorial. Feel free to go back to it if you want to complete the game.

==== '''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 '''NewTrick'''
* If this is the last trick (no more cards in end) and it's finished, we need to go to '''EndHand'''

For now, let's return '''PlayerTurn'''. We'll implement the logic later.<pre>
<?php

namespace Bga\Games\Heartsclay\States;

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

class NextPlayer extends \Bga\GameFramework\States\GameState
{
public function __construct(protected Game $game)
{
parent::__construct(
$game,
id: 32,
type: StateType::GAME,
description: "",
);
}

public function onEnteringState(): int
{
return PlayerTurn::class;
}
}

</pre>

==== '''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'''.

<pre>
<?php

namespace Bga\Games\Heartsclay\States;

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

class EndHand extends \Bga\GameFramework\States\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>

==== State Logic ====

===== New Hand =====
We need to:

# Move all cards to the deck
# Shuffle the cards
# Deal the cards to the players
# Reset the "alreadyPlayedHearts" state

Here's the code:<pre>
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->notify->player($player_id, 'newHand', '', array('cards' => $cards));
}
$game->setGameStateValue('alreadyPlayedHearts', 0);
return NewTrick::class;
}
</pre>

===== New Trick =====
We only need to reset the trick color<pre>
public function onEnteringState()
{
// New trick: active the player who wins the last trick, or the player who own the club-2 card
// Reset trick color to 0 (= no color)
$this->game->setGameStateInitialValue('trickColor', 0);
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
// Move all cards to "cardswon" of the given player
$best_value_player_id = $game->activeNextPlayer(); // TODO figure out winner of trick
$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
return NewTrick::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 Action =====
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 \BgaUserException('Not implemented: ${player_id} played card ${card_id}', args: [
'player_id' => $activePlayerId,
'card_id' => $cardId,
]);
return NextPlayer::class; // after the action, we move to the next player
}
</pre>

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

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<pre>
onUpdateActionButtons: function (stateName, args) {
console.log("onUpdateActionButtons: " + stateName, args);

if (this.isCurrentPlayerActive()) {
switch (stateName) {
case "playerTurn":
break;
}
}
},
</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 onPlayerHandSelectionChanged with
<pre>
onPlayerHandSelectionChanged : function() {
var items = this.playerHand.getSelectedItems();

if (items.length > 0) {
var action = 'actPlayCard';
if (this.checkAction(action, true)) {
// Can play a card
var card_id = items[0].id;
this.bgaPerformAction(action, {
card_id : card_id,
});

this.playerHand.unselectAll();
} else if (this.checkAction('actGiveCards')) {
// Can give cards => let the player select some cards
} else {
this.playerHand.unselectAll();
}
}
},
</pre>

Now when you click on card you should get a server response: Not implemented...

Lets implement it, in Game.php
<pre>

function actPlayCard(int $card_id) {
$player_id = $this->getActivePlayerId();
$this->cards->moveCard($card_id, 'cardsontable', $player_id);
// XXX check rules here
$currentCard = $this->cards->getCard($card_id);
// And notify
$this->notify->all('playCard', clienttranslate('${player_name} plays ${value_displayed} ${color_displayed}'), array (
'i18n' => array ('color_displayed','value_displayed' ),'card_id' => $card_id,'player_id' => $player_id,
'player_name' => $this->getActivePlayerName(),
'value' => $currentCard ['type_arg'],
'value_displayed' => self::$CARD_TYPES [$currentCard ['type_arg']] ['name'],
'color' => $currentCard ['type'],
'color_displayed' => self::$CARD_SUITS [$currentCard ['type']] ['name'] ));
// Next player
$this->gamestate->nextState('playCard');
}

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

<pre>
setupNotifications : function() {
console.log('notifications subscriptions setup');
// table of notif type to delay in milliseconds
const notifs = [
['newHand', 1],
['playCard', 100],
];

notifs.forEach((notif) => {
dojo.subscribe(notif[0], this, `notif_${notif[0]}`);
this.notifqueue.setSynchronous(notif[0], notif[1]);
});

},

notif_newHand : function(notif) {
// We received a new full hand of 13 cards.
this.playerHand.removeAll();

for ( var i in notif.args.cards) {
var card = notif.args.cards[i];
var color = card.type;
var value = card.type_arg;
this.playerHand.addToStockWithId(this.getCardUniqueId(color, value), card.id);
}
},

notif_playCard : function(notif) {
// Play a card on the table
this.playCardOnTable(notif.args.player_id, notif.args.color, notif.args.value, notif.args.card_id);
},
</pre>

Now it actually works through the server when you click on card - the move is recorded. If you test it now 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 we need to send notification about it
and have a handler for it

So in Game.php file add notification in stNextPlayer function after moveAllCardsInLocation call:

<pre>
// Notify
// 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 = $this->loadPlayersBasicInfos();
$this->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']
) );
$this->notify->all( 'giveAllCardsToPlayer','', array(
'player_id' => $best_value_player_id
) );
</pre>

And in .js file add 2 more notification handlers.

This is to subscribe in setupNotifications function
<pre>
const notifs = [
...
['trickWin', 1000],
['giveAllCardsToPlayer', 600],
];
</pre>

And these are handlers
<pre>
notif_trickWin : function(notif) {
// We do nothing here (just wait in order players can view the 4 cards played before they're gone.
},
notif_giveAllCardsToPlayer : function(notif) {
// Move all cards on table to given table, then destroy them
var winner_id = notif.args.player_id;
for ( var player_id in this.gamedatas.players) {
var anim = this.slideToObject('cardontable_' + player_id, 'overall_player_board_' + winner_id);
dojo.connect(anim, 'onEnd', function(node) {
dojo.destroy(node);
});
anim.play();
}
},
</pre>

So 'trickWin' notification does not do much except it will delay the processing of next notification by 1 second (1000 ms)
and it will log the message (that happens independently of what handler does).
<i>Note: if on the other hand you don't want to log but want to do something else, send an empty message</i>

Now after the trick you see all cards move towards the "player's stash".

==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 'trickColor' which we already conveniently created.

In Game.php file find the actPlayCard function and add this before notify functions
$currentTrickColor = $this->getGameStateValue( 'trickColor' ) ;
if( $currentTrickColor == 0 )
$this->setGameStateValue( 'trickColor', $currentCard['type'] );

This will make sure we remember the first suit being played, now to use it modify the stNextPlayer function to fix our TODO comment
<pre>
function stNextPlayer() {
// Active next player OR end the trick and go to the next trick OR end the hand
if ($this->cards->countCardInLocation('cardsontable') == 4) {
// This is the end of the trick
$cards_on_table = $this->cards->getCardsInLocation('cardsontable');
$best_value = 0;
$best_value_player_id = null;
$currentTrickColor = $this->getGameStateValue('trickColor');
foreach ( $cards_on_table as $card ) {
// Note: type = card color
if ($card ['type'] == $currentTrickColor) {
if ($best_value_player_id === null || $card ['type_arg'] > $best_value) {
$best_value_player_id = $card ['location_arg']; // Note: location_arg = player who played this card on table
$best_value = $card ['type_arg']; // Note: type_arg = value of the card
}
}
}

// Active this player => he's the one who starts the next trick
$this->gamestate->changeActivePlayer( $best_value_player_id );

// Move all cards to "cardswon" of the given player
$this->cards->moveAllCardsInLocation('cardsontable', 'cardswon', null, $best_value_player_id);

// Notify
// ... same code here 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, also
we want to show that in the log.
In addition scoring can be shown in [[Game_interface_logic:_yourgamename.js#Scoring_dialogs|Scoring Dialog]] using tableWindow notification, but it is a tutorial on its own and you can do it as homework (it is part of original heart game).

so in Game.php our stEndHand function will look like

<pre>
function stEndHand() {
// Count and score points, then end the game or go to the next hand.
$players = $this->loadPlayersBasicInfos();
// Gets all "hearts" + queen of spades

$player_to_points = array ();
foreach ( $players as $player_id => $player ) {
$player_to_points [$player_id] = 0;
}
$cards = $this->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) {
$this->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 ($this->playerScore->getMin() <= -100) {
// Trigger the end of the game !
$this->gamestate->nextState("endGame");
return;
}

$this->gamestate->nextState("nextHand");
}
</pre>

So it should more less work now, including end of game condition. Try to play it!

==Additional stuff==

The following things were not implemented and can add them yourself by looking at the code of original hearts game:

*Remove debug code from setupNewGame to deal cards, cards are now dealt in stNewHand state handler
*Rule checking and rule enforcements in actPlayCard function
*Start scoring with 100 points each and end when <= 0
*Fix scoring rules with Q of spades and 26 point reverse scoring
*First player one with 2 club
*Add progress handling
*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

2025-10-05T20:48:18Z

ShaharHarshuv: /* State Machine */ Update to modern States/

{{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]]).
* Know the rules for Hearts
* 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]

== 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. 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.
</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 full game can be found in your FTP home folder, after getting read-only access: https://en.doc.boardgamearena.com/First_steps_with_BGA_Studio#Set_up_dev_environment_ide,_editor_and_File_Sync

== 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://github.com/elaskavaia/bga-heartsla/blob/4b3a73eeb5acae961ade18473af119e8ce8d1a8f/img/cards.jpg hearts img/cards.jpg] into img/ folder of your project.
<blockquote>There are better quality deck of cards image at https://en.doc.boardgamearena.com/Common_board_game_elements_image_resources</blockquote>

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>
document.getElementById('game_play_area').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 (the image slightly obsolete, you may see more stuff there and different prompt).

[[File:Heartsla-tpl2.png]]

Now lets add a card into the hand, just so you can feel it. Edit the html string we inserted earlier and a playertablecard div inside a hand div
<pre>
...
<div id="myhand">
<div class="playertablecard"></div>
</div>
...
</pre>

Edit .css file
<pre>
.playertablecard {
display: inline-block;
position: relative;
margin-top: 5px;
width: 72px;
height: 96px;
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:

[[File:Heartsla-tpl3.png]]

Awesome! Now lets do the rest of layout.

Note: If you don't see the card a) check it was synced to remote folder b) force reload page

Let's complete the template string we created for the hand. You template should have this code, just leave it there
<pre>

// Example to add a div on the game area
document.getElementById("game_play_area").insertAdjacentHTML("beforeend",
`
<div id="player-tables"></div>
`
);
</pre>

Then change the following template code to this
<pre>
// Setting up player boards
var numPlayers = Object.keys(gamedatas.players).length;
Object.values(gamedatas.players).forEach((player, index) => {
document.getElementById("player-tables").insertAdjacentHTML(
"beforeend",
`
<div class="playertable whiteblock playertable_${DIRECTIONS[numPlayers][index]}">
<div class="playertablename" style="color:#${player.color};"><span class="dealer_token" id="dealer_token_p${player.id}">🃏 </span>${player.name}</div>
<div class="playertablecard" id="playertablecard_${player.id}"></div>
<div class="playertablename" id="hand_score_wrap_${player.id}"><span class="hand_score_label"></span> <span id="hand_score_${player.id}"></span></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
heartslav.js:68 Uncaught (in promise) ReferenceError: DIRECTIONS is not defined

For this new code to work, we need to add a constant at the beginning of the JS file, defining the expected position of each player (right after copyright comment):
<pre>
const DIRECTIONS = {
3: ['S', 'W', 'E'],
4: ['S', 'W', 'N', 'E'],
};
</pre>

Reload. If everything went well you should see this:

[[File:Hearts all rows.png|alt=Display a list of all players, with a dummy card in each position]]

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>
/** Table layout **/

#player-tables {
position: relative;
width: 710px;
height: 340px;
}

.playertablename {
font-weight: bold;
}

.playertable {
position: absolute;
text-align: center;
width: 180px;
height: 130px;
}

.playertable_N {
left: 50%;
top: 0px;
margin-left: -90px; /* half of 180 */
}
.playertable_S {
left: 50%;
bottom: 0px;
margin-left: -90px; /* half of 180 */
}
.playertable_W {
left: 0px;
top: 50%;
margin-top: -55px; /* half of 130 */
}
.playertable_E {
right: 0px;
top: 50%;
margin-top: -55px; /* half of 130 */
}
</pre>

Now you force Reload and you should see this:
[[File:Heartsla-tpl5.png]]

This is almost all we need for graphics and layout, there are few tweaks left there but lets do some more heavy lifting now.

<i>Note: if you did not see changes you may have not force reloaded, force means you use Ctrl+F5 or Cltr+Shift-R, if you don't "force" browser will use cached version of images! Which is not what you just changed</i>

<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 JS Stock ==

The BGA framework provides a few out of the box classes to deal with cards. The client side
contains a class called [[Stock]] and it can be used for any dynamic html "pieces" management that uses
common sprite images. 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 13x4 grid of images stitched together,
which is a very efficient way to transport images. So we will use the Stock class to mark up these images and create
"card" divs for us.

First, we need to add '''ebg/stock''' as a dependency in the .js file:
<pre>
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/stock" /// <==== HERE, don't forget comma before
],
</pre>

Then add this to the Javascript constructor, this will define size of our cards
<pre>
console.log('hearts constructor');
this.cardwidth = 72;
this.cardheight = 96;
</pre>

The stock is initialized in the Javascript "setup" method, after we have created the "myhand" element", like this:
<pre>
// TODO: Set up your game interface here, according to "gamedatas"

// Player hand
this.playerHand = new ebg.stock(); // new stock object for hand
this.playerHand.create( this, $('myhand'), this.cardwidth, this.cardheight );
</pre>

As parameters of the "create" method, we provided the width/height of an item (a card), and the container div "myhand" - which is an id of "div" element we have created before.

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

Here's how we tell stock what item types to display (add after .create):
<pre>
this.playerHand.image_items_per_row = 13; // 13 images per row

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

And add this function to the utilities section
<pre>
// Get card unique identifier based on its color and value
getCardUniqueId : function(color, value) {
return (color - 1) * 13 + (value - 2);
},
</pre>

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

Note: we need to generate a unique ID for each type of card based on its color and value. For that we create a function '''getCardUniqueId'''. The type is the unique identifier of the TYPE of the card, e.g., the queen of spades encoded as an integer. If our deck had 2 standard card decks we would have had 2 queens of spades; they would share the same type and the same image but would have different ids. NOTE: It's unfortunate that they named this '''getCardUniqueId'''; it should have been '''getCardUniqueType''', because it really isn't an id, but a TYPE of card. The type of the item should either be a reversible function of its properties (i.e., kind of suite * 13 + value) or just an enumerator described in material.inc.php. In this specific case it's a synthetic type id, which also the same as the number of the card in the sprite image (i.e., if you enumerate each image in sprite going left to right, then top to bottom).

Now let's add the 5 of Hearts to the player's hand just for fun (this code will go in setup method after types initialization):

<pre>
// 2 = hearts, 5 is 5, and 42 is the card id, which normally would come from db
this.playerHand.addToStockWithId( this.getCardUniqueId( 2, 5 ), 42 );
</pre>

This will add the card with id 42 and type 16 ( (2-1)*13+(5-2)=16 ).

Note that number 16 would not be something you can see in database, Deck database will have separate field for type and type_arg where type is suite and type_arg is number, so its not the same thing, but you can use same formula to convert. Number 42 on the other hand would be id field in database. But we get to database in the later section.

If you reload now you should see the 5 of hearts in "your hand".

You may see some weird graphics glitches - its because we did not remove our hack with background from .css yet. You can go to .css file now and remove line with comment "temp hack to see it".

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, after this.playerHand is initialised:

dojo.connect( this.playerHand, 'onChangeSelection', this, 'onPlayerHandSelectionChanged' );

Then find the Player's action comment section in .js file and add a handler after the comment:

<pre>
///////////////////////////////////////////////////
//// Player's action

onPlayerHandSelectionChanged: function () {
var items = this.playerHand.getSelectedItems();

if (items.length > 0) {
if (this.checkAction("actPlayCard", true)) {
// Can play a card

var card_id = items[0].id;
console.log("on playCard " + card_id);

this.playerHand.unselectAll();
} else if (this.checkAction("actGiveCards")) {
// Can give cards => let the player select some cards
} else {
this.playerHand.unselectAll();
}
}
},
</pre>

''Note : If you already have an example handler <code>onCardClick: function( card_id )</code>, go ahead and remove that handler, it is a duplicate of what we are implementing in this tutorial and may cause issues later on.''

The function name of the handler is 4th parameter of the dojo.connect function. Make sure you spell it correctly or there will be unpredictable effects.

Now if you reload, open the Javascript Console (F12), and then click on the card in My Hand, you should see:
on playCard 42
printed on the console

''Note : You need to be the active player to have rights to play a card and so log your message in the console''

== 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 ====
To modify the schema, first exit your existing game(s). Open '''dbmodel.sql''' file and uncomment the card table creation.

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

This is the "card" table which will be managed by the Deck php class.

In addition we want a little piece of information in the players table:

-- add info about first player
ALTER TABLE `player` ADD `player_first` BOOLEAN NOT NULL DEFAULT '0';

Not sure why they put this into the player table, as we could use a global db variable to hold first player as easily.
But I am just following the existing code more-or-less. It is not recommended to modify player table in general.

=== Game State Variables ===
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>
parent::__construct();
$this->initGameStateLabels(
[
"currentHandType" => 10,
"trickColor" => 11,
"alreadyPlayedHearts" => 12,
]
);;

$this->cards = $this->deckFactory->createDeck('card');
</pre>

If you see errors in IDE its because we also have to declared "cards" as class member, add ''public $cards;'' before the contructor.

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:

*"trickColor": numbers from 1 to 4 that map to card suit (not sure why it's called color; maybe it's a translation from French);
*"alreadyPlayedHearts": a boolean flag (0 or 1) indicating whether somebody used hearts on the trick;
*"currentHandType": stores the value to indicate who to give cards to during exchange.

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>

Since we changed the db, 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>

Code Rev [https://github.com/elaskavaia/bga-heartsla/tree/acd1926a6c09dc9afd0752cb6b78eef17c5dfe5c]

=== 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 "TODO: Setup the initial game situation here" comment.
<pre>
// Init global values with their initial values

// Note: hand types: 0 = give 3 cards to player on the left
// 1 = give 3 cards to player on the right
// 2 = give 3 cards to player opposite
// 3 = keep cards
$this->setGameStateInitialValue('currentHandType', 0);

// Set current trick color to zero (= no trick color)
$this->setGameStateInitialValue('trickColor', 0);

// Mark if we already played hearts during this hand
$this->setGameStateInitialValue('alreadyPlayedHearts', 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.
<pre>
// Create cards
$cards = [];
foreach (self::$CARD_SUITS as $suit => $suit_info) {
// spade, heart, diamond, club
foreach (self::$CARD_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 ''self:$CARD_SUITS''.
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 (if you already have ''self::$CARD_TYPES'', replace it)

<pre>
elf::$CARD_SUITS = [
1 => [
'name' => clienttranslate('Spade'),
],
2 => [
'name' => clienttranslate('Heart'),
],
3 => [
'name' => clienttranslate('Club'),
],
4 => [
'name' => clienttranslate('Diamond'),
]
];

self::$CARD_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 declared these fields in the class
private static array $CARD_SUITS;
private static array $CARD_TYPES;

==== 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) {
$cards = $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', $current_player_id);

// 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 .js file in the setup function (which is the receiver of getAllDatas) replace our hack of putting 5 of Hearts directly into the hand with:

<pre>
// Cards in player's hand
for (var i in this.gamedatas.hand) {
var card = this.gamedatas.hand[i];
var color = card.type;
var value = card.type_arg;
this.playerHand.addToStockWithId(this.getCardUniqueId(color, value), card.id);
}
</pre>

At this point, you could start a new game and each player should see their hand!

=== Cards on Table ===
To the setup method, add:
// Cards played on table
for (i in this.gamedatas.cardsontable) {
var card = this.gamedatas.cardsontable[i];
var color = card.type;
var value = card.type_arg;
var player_id = card.location_arg;
this.playCardOnTable(player_id, color, value, card.id);
}
Add the '''playCardOnTable''' function in the "utilities" section.

<pre>
playCardOnTable : function(player_id, color, value, card_id) {
// player_id => direction
this.addTableCard(value, color, player_id, player_id);

if (player_id != this.player_id) {
// Some opponent played a card
// Move card from player panel
this.placeOnObject('cardontable_' + player_id, 'overall_player_board_' + player_id);
} else {
// You played a card. If it exists in your hand, move card from there and remove
// corresponding item

if ($('myhand_item_' + card_id)) {
this.placeOnObject('cardontable_' + player_id, 'myhand_item_' + card_id);
this.playerHand.removeFromStockById(card_id);
}
}

// In any case: move it to its final destination
this.slideToObject('cardontable_' + player_id, 'playertablecard_' + player_id).play();
},
</pre>

For this to work we also need to define the addTableCard
<pre>
addTableCard(value, color, card_player_id, playerTableId) {
const x = value - 2;
const y = color - 1;
document.getElementById('playertablecard_' + playerTableId).insertAdjacentHTML('beforeend', `
<div class="card cardontable" id="cardontable_${card_player_id}" style="background-position:-${x}00% -${y}00%"></div>
`);
},
</pre>

What this does is basically create another card object, because if it is not our card it's not in our hand (Stock) so
we have to create it out of thin air. Now we have an object with an id of 'cardontable_' + player_id. Depending
on who is playing it we either place it on the player miniboard or in hand (and remove it from hand stock). Then we animate the card move.

We also should fix our .css file now to add style for cardontable and REMOVE background for playertablecard which really is a placeholder div and not a card. (Don't miss the remove step; it will be all screwy if you do!)

<pre>
.playertablecard {
display: inline-block;
position: relative;
margin-top: 5px;
width: 72px;
height: 96px;
/* we remove background-image here */
}

/*** cards on table ***/

.cardontable {
position: absolute;
width: 72px;
height: 96px;
background-image: url('img/cards.jpg');
}
</pre>

Next, we will hook-up clicking on card and test if our ''playCardOnTable'' works.

Find ''onPlayerHandSelectionChanged'' function in the JS file, we should have logging there like ''console.log("on playCard "+card_id);''
So after that insert this (Note: this code is for testing we will replace it with server interaction after we test it.):
<pre>
console.log("on playCard " + card_id);
// type is (color - 1) * 13 + (value - 2)
var type = items[0].type;
var color = Math.floor(type / 13) + 1;
var value = (type % 13) + 2;

this.playCardOnTable(this.player_id, color, value, card_id);
</pre>
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]]

Code Rev [https://github.com/elaskavaia/bga-heartsla/tree/0ed80e254a6d0c29f267b308d1c2016db90fd4f6]

==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. 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 is selected who will start a new trick ("NewTrick")
*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) ("NextHand")

=== Creating the basic states ===
Let's create our first state - "NewHand". Create a new file under "module/php/State" (you can delete the existing files there) and name it "'''NewHand.php'''".
<pre>
<?php

namespace Bga\Games\Heartsclay\States;

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

class NewHand extends \Bga\GameFramework\States\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
description: "",
updateGameProgression: true, // entering this state can update the progress bar of the game
);
}

// The action we do when entering the state
public function onEnteringState()
{
// TODO: implement logic
return NewTrick::class;
}
}

</pre>
You can read more about it here: [[State classes: State directory]]

Let's implement the other states:

==== '''NewTrick.php''' ====
<pre>
<?php

namespace Bga\Games\Heartsclay\States;

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

class NewTrick extends \Bga\GameFramework\States\GameState
{
public function __construct(protected Game $game)
{
parent::__construct(
$game,
id: 30,
type: StateType::GAME,
description: "",
);
}

public function onEnteringState()
{
// TODO: implement logic
return PlayerTurn::class;
}
}

</pre>

==== '''PlayerTurn.php''' ====
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

namespace Bga\Games\Heartsclay\States;

use Bga\GameFramework\StateType;
use Bga\Games\Heartsclay\Game;
use Bga\GameFramework\States\PossibleAction;

class PlayerTurn extends \Bga\GameFramework\States\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): void
{
// 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 \BgaUserException('Not implemented: zombie for player ${player_id}', args: [
'player_id' => $playerId,
]);
}
}

</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 not implement this as part of a tutorial. Feel free to go back to it if you want to complete the game.

==== '''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 '''NewTrick'''
* If this is the last trick (no more cards in end) and it's finished, we need to go to '''EndHand'''

For now, let's return '''PlayerTurn'''. We'll implement the logic later.<pre>
<?php

namespace Bga\Games\Heartsclay\States;

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

class NextPlayer extends \Bga\GameFramework\States\GameState
{
public function __construct(protected Game $game)
{
parent::__construct(
$game,
id: 32,
type: StateType::GAME,
description: "",
);
}

public function onEnteringState(): int
{
return PlayerTurn::class;
}
}

</pre>

==== '''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'''.

<pre>
<?php

namespace Bga\Games\Heartsclay\States;

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

class EndHand extends \Bga\GameFramework\States\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>

==== State Logic ====

===== New Hand =====
We need to:

# Move all cards to the deck
# Shuffle the cards
# Deal the cards to the players
# Reset the "alreadyPlayedHearts" state

Here's the code:<pre>
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->notify->player($player_id, 'newHand', '', array('cards' => $cards));
}
$game->setGameStateValue('alreadyPlayedHearts', 0);
return NewTrick::class;
}
</pre>

===== New Trick =====
We only need to reset the trick color<pre>
public function onEnteringState()
{
// New trick: active the player who wins the last trick, or the player who own the club-2 card
// Reset trick color to 0 (= no color)
$this->game->setGameStateInitialValue('trickColor', 0);
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
// Move all cards to "cardswon" of the given player
$best_value_player_id = $game->activeNextPlayer(); // TODO figure out winner of trick
$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
return NewTrick::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 Action =====
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)
{
$player_id = $this->game->getActivePlayerId();
throw new \BgaUserException('Not implemented: ${player_id} played card ${card_id}', args: [
'player_id' => $player_id,
'card_id' => $cardId,
]);
return NextPlayer::class; // after the action, we move to the next player
}
</pre>

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

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<pre>
onUpdateActionButtons: function (stateName, args) {
console.log("onUpdateActionButtons: " + stateName, args);

if (this.isCurrentPlayerActive()) {
switch (stateName) {
case "playerTurn":
break;
}
}
},
</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.

Eventhough we can it ajax call the API now called "bgaPerformAction" and this is what you should be using.

So in .js code replace onPlayerHandSelectionChanged with
<pre>
onPlayerHandSelectionChanged : function() {
var items = this.playerHand.getSelectedItems();

if (items.length > 0) {
var action = 'actPlayCard';
if (this.checkAction(action, true)) {
// Can play a card
var card_id = items[0].id;
this.bgaPerformAction(action, {
card_id : card_id,
});

this.playerHand.unselectAll();
} else if (this.checkAction('actGiveCards')) {
// Can give cards => let the player select some cards
} else {
this.playerHand.unselectAll();
}
}
},
</pre>

Now when you click on card you should get a server response: Not implemented...

Lets implement it, in Game.php
<pre>

function actPlayCard(int $card_id) {
$player_id = $this->getActivePlayerId();
$this->cards->moveCard($card_id, 'cardsontable', $player_id);
// XXX check rules here
$currentCard = $this->cards->getCard($card_id);
// And notify
$this->notify->all('playCard', clienttranslate('${player_name} plays ${value_displayed} ${color_displayed}'), array (
'i18n' => array ('color_displayed','value_displayed' ),'card_id' => $card_id,'player_id' => $player_id,
'player_name' => $this->getActivePlayerName(),
'value' => $currentCard ['type_arg'],
'value_displayed' => self::$CARD_TYPES [$currentCard ['type_arg']] ['name'],
'color' => $currentCard ['type'],
'color_displayed' => self::$CARD_SUITS [$currentCard ['type']] ['name'] ));
// Next player
$this->gamestate->nextState('playCard');
}

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

<pre>
setupNotifications : function() {
console.log('notifications subscriptions setup');
// table of notif type to delay in milliseconds
const notifs = [
['newHand', 1],
['playCard', 100],
];

notifs.forEach((notif) => {
dojo.subscribe(notif[0], this, `notif_${notif[0]}`);
this.notifqueue.setSynchronous(notif[0], notif[1]);
});

},

notif_newHand : function(notif) {
// We received a new full hand of 13 cards.
this.playerHand.removeAll();

for ( var i in notif.args.cards) {
var card = notif.args.cards[i];
var color = card.type;
var value = card.type_arg;
this.playerHand.addToStockWithId(this.getCardUniqueId(color, value), card.id);
}
},

notif_playCard : function(notif) {
// Play a card on the table
this.playCardOnTable(notif.args.player_id, notif.args.color, notif.args.value, notif.args.card_id);
},
</pre>

Now it actually works through the server when you click on card - the move is recorded. If you test it now 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 we need to send notification about it
and have a handler for it

So in Game.php file add notification in stNextPlayer function after moveAllCardsInLocation call:

<pre>
// Notify
// 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 = $this->loadPlayersBasicInfos();
$this->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']
) );
$this->notify->all( 'giveAllCardsToPlayer','', array(
'player_id' => $best_value_player_id
) );
</pre>

And in .js file add 2 more notification handlers.

This is to subscribe in setupNotifications function
<pre>
const notifs = [
...
['trickWin', 1000],
['giveAllCardsToPlayer', 600],
];
</pre>

And these are handlers
<pre>
notif_trickWin : function(notif) {
// We do nothing here (just wait in order players can view the 4 cards played before they're gone.
},
notif_giveAllCardsToPlayer : function(notif) {
// Move all cards on table to given table, then destroy them
var winner_id = notif.args.player_id;
for ( var player_id in this.gamedatas.players) {
var anim = this.slideToObject('cardontable_' + player_id, 'overall_player_board_' + winner_id);
dojo.connect(anim, 'onEnd', function(node) {
dojo.destroy(node);
});
anim.play();
}
},
</pre>

So 'trickWin' notification does not do much except it will delay the processing of next notification by 1 second (1000 ms)
and it will log the message (that happens independently of what handler does).
<i>Note: if on the other hand you don't want to log but want to do something else, send an empty message</i>

Now after the trick you see all cards move towards the "player's stash".

==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 'trickColor' which we already conveniently created.

In Game.php file find the actPlayCard function and add this before notify functions
$currentTrickColor = $this->getGameStateValue( 'trickColor' ) ;
if( $currentTrickColor == 0 )
$this->setGameStateValue( 'trickColor', $currentCard['type'] );

This will make sure we remember the first suit being played, now to use it modify the stNextPlayer function to fix our TODO comment
<pre>
function stNextPlayer() {
// Active next player OR end the trick and go to the next trick OR end the hand
if ($this->cards->countCardInLocation('cardsontable') == 4) {
// This is the end of the trick
$cards_on_table = $this->cards->getCardsInLocation('cardsontable');
$best_value = 0;
$best_value_player_id = null;
$currentTrickColor = $this->getGameStateValue('trickColor');
foreach ( $cards_on_table as $card ) {
// Note: type = card color
if ($card ['type'] == $currentTrickColor) {
if ($best_value_player_id === null || $card ['type_arg'] > $best_value) {
$best_value_player_id = $card ['location_arg']; // Note: location_arg = player who played this card on table
$best_value = $card ['type_arg']; // Note: type_arg = value of the card
}
}
}

// Active this player => he's the one who starts the next trick
$this->gamestate->changeActivePlayer( $best_value_player_id );

// Move all cards to "cardswon" of the given player
$this->cards->moveAllCardsInLocation('cardsontable', 'cardswon', null, $best_value_player_id);

// Notify
// ... same code here 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, also
we want to show that in the log.
In addition scoring can be shown in [[Game_interface_logic:_yourgamename.js#Scoring_dialogs|Scoring Dialog]] using tableWindow notification, but it is a tutorial on its own and you can do it as homework (it is part of original heart game).

so in Game.php our stEndHand function will look like

<pre>
function stEndHand() {
// Count and score points, then end the game or go to the next hand.
$players = $this->loadPlayersBasicInfos();
// Gets all "hearts" + queen of spades

$player_to_points = array ();
foreach ( $players as $player_id => $player ) {
$player_to_points [$player_id] = 0;
}
$cards = $this->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) {
$this->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 ($this->playerScore->getMin() <= -100) {
// Trigger the end of the game !
$this->gamestate->nextState("endGame");
return;
}

$this->gamestate->nextState("nextHand");
}
</pre>

So it should more less work now, including end of game condition. Try to play it!

==Additional stuff==

The following things were not implemented and can add them yourself by looking at the code of original hearts game:

*Remove debug code from setupNewGame to deal cards, cards are now dealt in stNewHand state handler
*Rule checking and rule enforcements in actPlayCard function
*Start scoring with 100 points each and end when <= 0
*Fix scoring rules with Q of spades and 26 point reverse scoring
*First player one with 2 club
*Add progress handling
*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]]

Players actions: yourgamename.action.php

2025-10-05T20:13:34Z

ShaharHarshuv:

<span style="color:red; font-size:20px;">'''IMPORTANT NOTE:''' This file is deprecated, you shouldn't need to use it if you use [https://en.doc.boardgamearena.com/Main_game_logic:_yourgamename.game.php#Actions_(autowired) Autowired action]</span>{{Studio_Framework_Navigation}}

== Purpose of this file ==

With this file, you define all the player entry points (i.e., possible game actions) for your game.

This file is a sort of "bridge" between the AJAX calls you perform from the Javascript client side, and your main PHP code in "yourgame.game.php".

The role of the methods defined in this file is to filter the arguments, format them a bit, and then call a corresponding PHP method from your main game logic ("yourgame.game.php" file).

Methods in this file should be short: no game logic must be introduced here.

==Example of typical action method==

(from Reversi example)

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

== Methods to use in action methods==

'''function setAjaxMode()'''

Must be used at the beginning of each action method.

'''function ajaxResponse()'''

Must be used at the end of each action method.

'''function getArg( $argName, $argType, $mandatory=false, $default=NULL, $argTypeDetails=array(), $bCanFail=false )'''

This method must be used to retrieve the arguments sent with your AJAX query.

You must ''not'' use "_GET", "_POST" or equivalent PHP variables to do this, as it is unsafe.

This method uses the following arguments:

*argName: the name of the argument to retrieve.
*argType: the type of the argument. You should use one of the following:
'AT_int' for an integer
'AT_posint' for a positive integer
'AT_float' for a float
'AT_bool' for 1/0/true/false
'AT_enum' for an enumeration (argTypeDetails lists the possible values as an array)
'AT_alphanum' for a string with 0-9a-zA-Z_ and space
'AT_alphanum_dash' for a string with 0-9a-zA-Z_- and space
'AT_numberlist' for a list of numbers separated with "," or ";" (example: 1,4;2,3;-1,2)
'AT_base64' for a base64-encoded string (SECURITY WARNING*)
'AT_json' for a JSON stringified string (SECURITY WARNING**)

*mandatory: specify "true" if the argument is mandatory.
*default: if mandatory=false, you can specify here a default value in case the argument is not present.
*argTypeDetails: used with the 'AT_enum'. Validates that the value passed in is in this list.
*bCanFail: if true, specify that it may be possible that the argument won't be of the type specified by argType (and then do not log this as a fatal error in the system, and return a standard exception to the player).

'''SECURITY WARNING''': If using AT_base64 or AT_json, or other undocumented unchecked types you must perform validation on unpacked data, i.e. do not use any of it unchecked, i.e. pass to DB queries or return back in notifications.

Here is an example of a sanity check for JSON :

public function actMyAction()
{
$this->setAjaxMode();
$args = $this->getArg('actionArgs', AT_json, true);
$this->validateJSonAlphaNum($args, 'actionArgs');
$this->game->actMyAction($args);
$this->ajaxResponse();
}

public function validateJSonAlphaNum($value, $argName = 'unknown')
{
if (is_array($value)) {
foreach ($value as $key => $v) {
$this->validateJSonAlphaNum($key, $argName);
$this->validateJSonAlphaNum($v, $argName);
}
return true;
}
if (is_int($value)) {
return true;
}
$bValid = preg_match("/^[_0-9a-zA-Z- ]*$/", $value) === 1;
if (!$bValid) {
throw new \BgaSystemException("Bad value for: $argName", true, true, FEX_bad_input_argument);
}
return true;
}

'''AT_enum and argTypeDetails Example'''

Validates that the value of 'myarg' is either 'apple', 'orange', or 'banana'

$myarg = $this->getArg( 'myarg', AT_enum, false, null, [ 'apple', 'orange', 'banana' ] ); // optional enum

'''function isArg( $argName )'''

This is a useful method when you only want to check if an argument is present or not present in your AJAX request (and don't care about the value).

It returns "true" or "false" according to whether "argName" has been specified as an argument of the AJAX request or not.

==Useful tip: retrieve a list of numbers==

If your Javascript sends a list of integers separated by ";" (example: "1;2;3;4") as an argument, you can transform them into a PHP array with the following:

<pre>
public function actPlayCards()
{
$this->setAjaxMode();

$card_ids_raw = $this->getArg( "card_ids", AT_numberlist, true );

// Removing last ';' if exists
if( substr( $card_ids_raw, -1 ) == ';' )
$card_ids_raw = substr( $card_ids_raw, 0, -1 );
if( $card_ids_raw == '' )
$card_ids = array();
else
$card_ids = explode( ';', $card_ids_raw );

$this->game->actPlayCards( $card_ids );
$this->ajaxResponse( );
}
</pre>

==Example pass array of Id's==

If your Javascript sends a list of object denomated by alphanumerical tokenId, you can use AT_alphanum type and space as array separator:

<pre>
// sending 'card_ids' => "card_1 card_23 card_12"
public function actPlayCards() {
$this->setAjaxMode();

$card_ids_raw = $this->getArg( "card_ids", AT_alphanum, true );
$card_ids_raw = trim($card_ids_raw);

if( $card_ids_raw == '' )
$card_ids = array();
else
$card_ids = explode( ' ', $card_ids_raw );

$this->game->actPlayCards( $card_ids );
$this->ajaxResponse( );
}
</pre>

==Retrieving data from ajax call==

Note that this is not possible to return any result from a player action: it should return nothing (action went fine) or an exception (action unsuccessful).

The typical way to implement this is using games states with game state arguments. Eventually, use player notifications.

==Game action handler==
This is a note on what you should be doing and not doing in ggg.game.php action handler vs in action.php action handler

action.php
*action handler in action.php should very simple and it should ONLY extract arguments from ajax call, pass them down to game handler
*it should not implement any game logic or check for validity beyong the syntax. I.e. DO NOT put checkAction this action.php

game.php
*call checkAction('actMyAction') first
* check arguments for game validity (i.e. player is not cheating), throw system exceptions if it is (usually this cases where JS side won't be sending it but you still have to check for it)
*perfom action and update database, can do more check if throw user exception if this is not valid move by the rules
*send notifications (must send notification even if empty if not transitioning in new state on some paths)
*transition to new state

[[Category:Studio]]

Tutorial reversi

2025-10-05T19:06:26Z

ShaharHarshuv: /* Build your States */

If you want to use TypeScript, you can '''check out an updated version''' of the [[BGA Type Safe Template: Reversi|Reversi Tutorial]] which uses the [[BGA Type Safe Template]]. '''Important note: BGA Type Safe Template is a project created by a developer that is not part of the BGA team, and is outdated. This is currently not officially supported by BGA.''' {{Studio_Framework_Navigation}}

== Introduction ==

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

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

== Create your first game ==

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

With the initial skeleton of code provided in your project, you can already start a game from the BGA Studio:
* Go to your [https://studio.boardgamearena.com/controlpanel studio Control panel], then Manage games and select your initial project. ''Note: there are warnings displayed about a missing BGG_ID and presentation text. You can ignore that for now.''
* Click the Play link next to your project name. This will open the Play page and offer to create a new table for your project. ''Optional: click the Heart icon to add your project to your favorite games list.''
* On the Play page, on the top of the page, make sure that your settings are "Simple game", "Real time" and "Manual".
* Click "Create table" to create a table of your project.
* For now, we are going to work with one player only, so use the (-) button to set the number of players to 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 "Game Information" section, click "Reload game informations".
* Finally, refresh the project page in your browser (usually CTRL-F5).

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

Sometimes the cache will keep your changes from showing. Since this is a possibility, it will be useful to know how to bypass the cache. To do so you may manually clear cache or use a shortcut to refresh and ignore the cached version of the page. Here's how

====== Windows ======
Chrome, Firefox, or Edge: Press <code>Ctrl+F5</code> or <code>Shift+F5</code> or <code>Ctrl+Shift+R</code>

====== Mac ======
Chrome or Firefox: Press <code>Shift+Command+R</code>

Safari for Mac: Press <code>Command+Option+E</code> to empty the cache, then hold down Shift and click Reload in the toolbar

== Make it look like Reversi ==

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

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

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

[[File:Board.jpg]]

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

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

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

<pre>
this.getGameAreaElement().insertAdjacentHTML('beforeend', `
<div id="board">
</div>
`);
</pre>

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

'''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, js template to the tpl, utility method in the js, adjusted the php file, and added the token to the board in the js file.

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

[[File:tokens.png]]

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

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

==== Style the Tokens in .css file ====
<pre>
.disc {
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>reversi.js</code> file) that will make a token appear on the board, using this template. Add under the section <code>//// Utility methods</code>:

<pre>
addDiscOnBoard: async function( x, y, 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.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 = array( "ffffff", "000000" );
</pre>

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

=== Test the Token ===
Now, to test if everything works fine

==== <code>addTokenOnBoard()</code> in .js file to Test ====
In <code>reversi.js</code>, in <code>setup: function</code>, under the code we added to generate the squares.
this.addDiscOnBoard(2, 2, this.player_id, 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(5) unsigned NOT NULL,
`board_y` smallint(5) unsigned NOT NULL,
`board_player` int(10) unsigned DEFAULT NULL,
PRIMARY KEY (`board_x`,`board_y`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
</pre>

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

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

Start a new game and verify a table is created.

== Setup the initial game position ==

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

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

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

$sql_values[] = "('$x','$y',$token_value)";
}
}
$sql .= implode( ',', $sql_values );
$this->DbQuery( $sql );
</pre>

==== Board Initialization Explanation ====

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

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

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

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

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

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

Next, you 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.player_id);</code>

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

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

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

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

[[File:reversi5.jpg]]

It starts to feel like Reversi here...

== 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/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 argPlayerTurn(int $activePlayerId): array
{
return [
'possibleMoves' => $this->game->getPossibleMoves($activePlayerId)
];
}
</pre>

<strong>Note:</strong> after this modification you will need to modify the <code>onUpdateActionButtons</code> function in your javascript to remove the references to <code>playableCardsIds</code> in order to launch a game, there will be javascript errors in the console as the code will blow up when it tries to loop over that array.

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

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

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

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

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

<pre>
updatePossibleMoves: function( possibleMoves )
{
// Remove current possible moves
document.querySelectorAll('.possibleMove').forEach(div => div.classList.remove('possibleMove'));

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

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

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

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

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

And here we are:

[[File:reversi8.jpg.jpg]]

==Let's play==

From now, it's better to restart a game with 2 players, because we are going to implement a complete Reversi turn. The summary of what we are going to do is:
*When we click on a 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: function( evt )
{
// Stop this event propagation
evt.preventDefault();
evt.stopPropagation();

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

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

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

What we do here is:
*We stop the propagation of the Javascript <code>onclick</code> event. Otherwise, it can lead to random behavior so it's always a good idea.
*We get the x/y coordinates of the square by using <code>evt.currentTarget.id</code>
* We check that clicked square has the <code>possibleMove</code> class, otherwise we know for sure that we can't play there.
*Finally, we make a call to the server using BGA <code>bgaPerformAction</code> method with argument x and y. This call will check that <code>actPlayDisc</code> action is possible, according to current game state (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->getBoard();
$turnedOverDiscs = $this->game->getTurnedOverDiscs( $x, $y, $activePlayerId, $board );

if( count( $turnedOverDiscs ) === 0 ) {
throw new \BgaSystemException("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

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

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

$this->game->DbQuery( $sql );
</pre>

we manage game statistics:
<pre>
// Statistics
$this->game->incStat( count( $turnedOverDiscs ), "turnedOver", $player_id );
if( ($x==1 && $y==1) || ($x==8 && $y==1) || ($x==1 && $y==8) || ($x==8 && $y==8) )
$this->game->incStat( 1, 'discPlayedOnCorner', $activePlayerId );
else if( $x==1 || $x==8 || $y==1 || $y==8 )
$this->game->incStat( 1, 'discPlayedOnBorder', $activePlayerId );
else if( $x>=3 && $x<=6 && $y>=3 && $y<=6 )
$this->game->incStat( 1, 'discPlayedOnCenter', $activePlayerId );
</pre>

Notify the turned discs:
<pre>
// Notify
$this->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->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 = (int)$this->game->getUniqueValueFromDB("SELECT COUNT(*) FROM `board` WHERE `board_player` = $playerId");
$this->playerScore->set($playerId, $tokens); // this will update the JS counter automatically
}
</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->activeNextPlayer());

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

if( ! isset( $player_to_discs[ null ] ) )
{
// Index 0 has not been set => there's no more free place on the board !
// => end of the game
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->getPossibleMoves( $player_id );
if( count( $possibleMoves ) == 0 )
{

// This player can't play
// Can his opponent play ?
$opponent_id = (int)$this->getUniqueValueFromDb( "SELECT player_id FROM player WHERE player_id!='$player_id' " );
if( count( $this->getPossibleMoves( $opponent_id ) ) == 0 )
{
// Nobody can move => end of the game
return ST_END_GAME;
}
else
{
// => pass his turn
return NextPlayer::class;
}
}
else
{
// This player can play. Give him some extra time
$this->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>reversi.js</code>, we tell BGA to listen to notifications we will add later (<code>playDisc</code> and <code>turnOverDiscs</code>) using promise-based notifications:

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

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

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

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

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

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

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

<pre>
animateTurnOverDisc: async function(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.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.wait(500); // for the flip animation removal to finish
},

notif_turnOverDiscs: async function( args )
{

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

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

}
</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->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) {
$count = 0;
while (intval($this->gamestate->getCurrentMainStateId()) < 99 && $count < $moves) {
$count++;
foreach($this->gamestate->getActivePlayerList() as $playerId) {
$playerId = (int)$playerId;
$this->gamestate->runStateClassZombie($this->gamestate->getCurrentState($playerId), $playerId);
}
}
}

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

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

2025-10-05T18:59:28Z

ShaharHarshuv: /* State Machine */ add warning for outdated instructions

{{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]]).
* Know the rules for Hearts
* 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]

== 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. 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.
</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 full game can be found in your FTP home folder, after getting read-only access: https://en.doc.boardgamearena.com/First_steps_with_BGA_Studio#Set_up_dev_environment_ide,_editor_and_File_Sync

== 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://github.com/elaskavaia/bga-heartsla/blob/4b3a73eeb5acae961ade18473af119e8ce8d1a8f/img/cards.jpg hearts img/cards.jpg] into img/ folder of your project.
<blockquote>There are better quality deck of cards image at https://en.doc.boardgamearena.com/Common_board_game_elements_image_resources</blockquote>

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>
document.getElementById('game_play_area').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 (the image slightly obsolete, you may see more stuff there and different prompt).

[[File:Heartsla-tpl2.png]]

Now lets add a card into the hand, just so you can feel it. Edit the html string we inserted earlier and a playertablecard div inside a hand div
<pre>
...
<div id="myhand">
<div class="playertablecard"></div>
</div>
...
</pre>

Edit .css file
<pre>
.playertablecard {
display: inline-block;
position: relative;
margin-top: 5px;
width: 72px;
height: 96px;
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:

[[File:Heartsla-tpl3.png]]

Awesome! Now lets do the rest of layout.

Note: If you don't see the card a) check it was synced to remote folder b) force reload page

Let's complete the template string we created for the hand. You template should have this code, just leave it there
<pre>

// Example to add a div on the game area
document.getElementById("game_play_area").insertAdjacentHTML("beforeend",
`
<div id="player-tables"></div>
`
);
</pre>

Then change the following template code to this
<pre>
// Setting up player boards
var numPlayers = Object.keys(gamedatas.players).length;
Object.values(gamedatas.players).forEach((player, index) => {
document.getElementById("player-tables").insertAdjacentHTML(
"beforeend",
`
<div class="playertable whiteblock playertable_${DIRECTIONS[numPlayers][index]}">
<div class="playertablename" style="color:#${player.color};"><span class="dealer_token" id="dealer_token_p${player.id}">🃏 </span>${player.name}</div>
<div class="playertablecard" id="playertablecard_${player.id}"></div>
<div class="playertablename" id="hand_score_wrap_${player.id}"><span class="hand_score_label"></span> <span id="hand_score_${player.id}"></span></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
heartslav.js:68 Uncaught (in promise) ReferenceError: DIRECTIONS is not defined

For this new code to work, we need to add a constant at the beginning of the JS file, defining the expected position of each player (right after copyright comment):
<pre>
const DIRECTIONS = {
3: ['S', 'W', 'E'],
4: ['S', 'W', 'N', 'E'],
};
</pre>

Reload. If everything went well you should see this:

[[File:Hearts all rows.png|alt=Display a list of all players, with a dummy card in each position]]

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>
/** Table layout **/

#player-tables {
position: relative;
width: 710px;
height: 340px;
}

.playertablename {
font-weight: bold;
}

.playertable {
position: absolute;
text-align: center;
width: 180px;
height: 130px;
}

.playertable_N {
left: 50%;
top: 0px;
margin-left: -90px; /* half of 180 */
}
.playertable_S {
left: 50%;
bottom: 0px;
margin-left: -90px; /* half of 180 */
}
.playertable_W {
left: 0px;
top: 50%;
margin-top: -55px; /* half of 130 */
}
.playertable_E {
right: 0px;
top: 50%;
margin-top: -55px; /* half of 130 */
}
</pre>

Now you force Reload and you should see this:
[[File:Heartsla-tpl5.png]]

This is almost all we need for graphics and layout, there are few tweaks left there but lets do some more heavy lifting now.

<i>Note: if you did not see changes you may have not force reloaded, force means you use Ctrl+F5 or Cltr+Shift-R, if you don't "force" browser will use cached version of images! Which is not what you just changed</i>

<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 JS Stock ==

The BGA framework provides a few out of the box classes to deal with cards. The client side
contains a class called [[Stock]] and it can be used for any dynamic html "pieces" management that uses
common sprite images. 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 13x4 grid of images stitched together,
which is a very efficient way to transport images. So we will use the Stock class to mark up these images and create
"card" divs for us.

First, we need to add '''ebg/stock''' as a dependency in the .js file:
<pre>
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/stock" /// <==== HERE, don't forget comma before
],
</pre>

Then add this to the Javascript constructor, this will define size of our cards
<pre>
console.log('hearts constructor');
this.cardwidth = 72;
this.cardheight = 96;
</pre>

The stock is initialized in the Javascript "setup" method, after we have created the "myhand" element", like this:
<pre>
// TODO: Set up your game interface here, according to "gamedatas"

// Player hand
this.playerHand = new ebg.stock(); // new stock object for hand
this.playerHand.create( this, $('myhand'), this.cardwidth, this.cardheight );
</pre>

As parameters of the "create" method, we provided the width/height of an item (a card), and the container div "myhand" - which is an id of "div" element we have created before.

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

Here's how we tell stock what item types to display (add after .create):
<pre>
this.playerHand.image_items_per_row = 13; // 13 images per row

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

And add this function to the utilities section
<pre>
// Get card unique identifier based on its color and value
getCardUniqueId : function(color, value) {
return (color - 1) * 13 + (value - 2);
},
</pre>

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

Note: we need to generate a unique ID for each type of card based on its color and value. For that we create a function '''getCardUniqueId'''. The type is the unique identifier of the TYPE of the card, e.g., the queen of spades encoded as an integer. If our deck had 2 standard card decks we would have had 2 queens of spades; they would share the same type and the same image but would have different ids. NOTE: It's unfortunate that they named this '''getCardUniqueId'''; it should have been '''getCardUniqueType''', because it really isn't an id, but a TYPE of card. The type of the item should either be a reversible function of its properties (i.e., kind of suite * 13 + value) or just an enumerator described in material.inc.php. In this specific case it's a synthetic type id, which also the same as the number of the card in the sprite image (i.e., if you enumerate each image in sprite going left to right, then top to bottom).

Now let's add the 5 of Hearts to the player's hand just for fun (this code will go in setup method after types initialization):

<pre>
// 2 = hearts, 5 is 5, and 42 is the card id, which normally would come from db
this.playerHand.addToStockWithId( this.getCardUniqueId( 2, 5 ), 42 );
</pre>

This will add the card with id 42 and type 16 ( (2-1)*13+(5-2)=16 ).

Note that number 16 would not be something you can see in database, Deck database will have separate field for type and type_arg where type is suite and type_arg is number, so its not the same thing, but you can use same formula to convert. Number 42 on the other hand would be id field in database. But we get to database in the later section.

If you reload now you should see the 5 of hearts in "your hand".

You may see some weird graphics glitches - its because we did not remove our hack with background from .css yet. You can go to .css file now and remove line with comment "temp hack to see it".

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, after this.playerHand is initialised:

dojo.connect( this.playerHand, 'onChangeSelection', this, 'onPlayerHandSelectionChanged' );

Then find the Player's action comment section in .js file and add a handler after the comment:

<pre>
///////////////////////////////////////////////////
//// Player's action

onPlayerHandSelectionChanged: function () {
var items = this.playerHand.getSelectedItems();

if (items.length > 0) {
if (this.checkAction("actPlayCard", true)) {
// Can play a card

var card_id = items[0].id;
console.log("on playCard " + card_id);

this.playerHand.unselectAll();
} else if (this.checkAction("actGiveCards")) {
// Can give cards => let the player select some cards
} else {
this.playerHand.unselectAll();
}
}
},
</pre>

''Note : If you already have an example handler <code>onCardClick: function( card_id )</code>, go ahead and remove that handler, it is a duplicate of what we are implementing in this tutorial and may cause issues later on.''

The function name of the handler is 4th parameter of the dojo.connect function. Make sure you spell it correctly or there will be unpredictable effects.

Now if you reload, open the Javascript Console (F12), and then click on the card in My Hand, you should see:
on playCard 42
printed on the console

''Note : You need to be the active player to have rights to play a card and so log your message in the console''

== 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 ====
To modify the schema, first exit your existing game(s). Open '''dbmodel.sql''' file and uncomment the card table creation.

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

This is the "card" table which will be managed by the Deck php class.

In addition we want a little piece of information in the players table:

-- add info about first player
ALTER TABLE `player` ADD `player_first` BOOLEAN NOT NULL DEFAULT '0';

Not sure why they put this into the player table, as we could use a global db variable to hold first player as easily.
But I am just following the existing code more-or-less. It is not recommended to modify player table in general.

=== Game State Variables ===
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>
parent::__construct();
$this->initGameStateLabels(
[
"currentHandType" => 10,
"trickColor" => 11,
"alreadyPlayedHearts" => 12,
]
);;

$this->cards = $this->deckFactory->createDeck('card');
</pre>

If you see errors in IDE its because we also have to declared "cards" as class member, add ''protected $cards;'' before the contructor.

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:

*"trickColor": numbers from 1 to 4 that map to card suit (not sure why it's called color; maybe it's a translation from French);
*"alreadyPlayedHearts": a boolean flag (0 or 1) indicating whether somebody used hearts on the trick;
*"currentHandType": stores the value to indicate who to give cards to during exchange.

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>

Since we changed the db, 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>

Code Rev [https://github.com/elaskavaia/bga-heartsla/tree/acd1926a6c09dc9afd0752cb6b78eef17c5dfe5c]

=== 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 "TODO: Setup the initial game situation here" comment.
<pre>
// Init global values with their initial values

// Note: hand types: 0 = give 3 cards to player on the left
// 1 = give 3 cards to player on the right
// 2 = give 3 cards to player opposite
// 3 = keep cards
$this->setGameStateInitialValue('currentHandType', 0);

// Set current trick color to zero (= no trick color)
$this->setGameStateInitialValue('trickColor', 0);

// Mark if we already played hearts during this hand
$this->setGameStateInitialValue('alreadyPlayedHearts', 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.
<pre>
// Create cards
$cards = [];
foreach (self::$CARD_SUITS as $suit => $suit_info) {
// spade, heart, diamond, club
foreach (self::$CARD_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 ''self:$CARD_SUITS''.
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 (if you already have ''self::$CARD_TYPES'', replace it)

<pre>
elf::$CARD_SUITS = [
1 => [
'name' => clienttranslate('Spade'),
],
2 => [
'name' => clienttranslate('Heart'),
],
3 => [
'name' => clienttranslate('Club'),
],
4 => [
'name' => clienttranslate('Diamond'),
]
];

self::$CARD_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 declared these fields in the class
private static array $CARD_SUITS;
private static array $CARD_TYPES;

==== 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) {
$cards = $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', $current_player_id);

// 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 .js file in the setup function (which is the receiver of getAllDatas) replace our hack of putting 5 of Hearts directly into the hand with:

<pre>
// Cards in player's hand
for (var i in this.gamedatas.hand) {
var card = this.gamedatas.hand[i];
var color = card.type;
var value = card.type_arg;
this.playerHand.addToStockWithId(this.getCardUniqueId(color, value), card.id);
}
</pre>

At this point, you could start a new game and each player should see their hand!

=== Cards on Table ===
To the setup method, add:
// Cards played on table
for (i in this.gamedatas.cardsontable) {
var card = this.gamedatas.cardsontable[i];
var color = card.type;
var value = card.type_arg;
var player_id = card.location_arg;
this.playCardOnTable(player_id, color, value, card.id);
}
Add the '''playCardOnTable''' function in the "utilities" section.

<pre>
playCardOnTable : function(player_id, color, value, card_id) {
// player_id => direction
this.addTableCard(value, color, player_id, player_id);

if (player_id != this.player_id) {
// Some opponent played a card
// Move card from player panel
this.placeOnObject('cardontable_' + player_id, 'overall_player_board_' + player_id);
} else {
// You played a card. If it exists in your hand, move card from there and remove
// corresponding item

if ($('myhand_item_' + card_id)) {
this.placeOnObject('cardontable_' + player_id, 'myhand_item_' + card_id);
this.playerHand.removeFromStockById(card_id);
}
}

// In any case: move it to its final destination
this.slideToObject('cardontable_' + player_id, 'playertablecard_' + player_id).play();
},
</pre>

For this to work we also need to define the addTableCard
<pre>
addTableCard(value, color, card_player_id, playerTableId) {
const x = value - 2;
const y = color - 1;
document.getElementById('playertablecard_' + playerTableId).insertAdjacentHTML('beforeend', `
<div class="card cardontable" id="cardontable_${card_player_id}" style="background-position:-${x}00% -${y}00%"></div>
`);
},
</pre>

What this does is basically create another card object, because if it is not our card it's not in our hand (Stock) so
we have to create it out of thin air. Now we have an object with an id of 'cardontable_' + player_id. Depending
on who is playing it we either place it on the player miniboard or in hand (and remove it from hand stock). Then we animate the card move.

We also should fix our .css file now to add style for cardontable and REMOVE background for playertablecard which really is a placeholder div and not a card. (Don't miss the remove step; it will be all screwy if you do!)

<pre>
.playertablecard {
display: inline-block;
position: relative;
margin-top: 5px;
width: 72px;
height: 96px;
/* we remove background-image here */
}

/*** cards on table ***/

.cardontable {
position: absolute;
width: 72px;
height: 96px;
background-image: url('img/cards.jpg');
}
</pre>

Next, we will hook-up clicking on card and test if our ''playCardOnTable'' works.

Find ''onPlayerHandSelectionChanged'' function in the JS file, we should have logging there like ''console.log("on playCard "+card_id);''
So after that insert this (Note: this code is for testing we will replace it with server interaction after we test it.):
<pre>
console.log("on playCard " + card_id);
// type is (color - 1) * 13 + (value - 2)
var type = items[0].type;
var color = Math.floor(type / 13) + 1;
var value = (type % 13) + 2;

this.playCardOnTable(this.player_id, color, value, card_id);
</pre>
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]]

Code Rev [https://github.com/elaskavaia/bga-heartsla/tree/0ed80e254a6d0c29f267b308d1c2016db90fd4f6]

==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. 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 is selected who will start a new trick ("NewTrick")
*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) ("NextHand")

'''<u>Warning</u>: The rest of the description in this section is out dated. Please consult with <nowiki>https://en.doc.boardgamearena.com/Tutorial_reversi#State_Machine</nowiki> to understand how to built state machines today.'''

The state handling spread across multiple files, so you have to make sure all pieces are connected together.
The state machine states.php defines all the states, and function handlers on php side in a form of string,
and if any of these functions are not implemented it would be very hard to debug because it will break in random places.

So .states.php (remove all template states and replace with these)

<pre>
$machinestates = array(
/// New hand
2 => array(
"name" => "newHand",
"description" => "",
"type" => "game",
"action" => "stNewHand",
"updateGameProgression" => true,
"transitions" => array( "" => 30 )
),

21 => array(
"name" => "giveCards",
"description" => clienttranslate('Some players must choose 3 cards to give to ${direction}'),
"descriptionmyturn" => clienttranslate('${you} must choose 3 cards to give to ${direction}'),
"type" => "multipleactiveplayer",
"action" => "stGiveCards",
"args" => "argGiveCards",
"possibleactions" => array( "actGiveCards" ),
"transitions" => array( "giveCards" => 22, "skip" => 22 )
),

22 => array(
"name" => "takeCards",
"description" => "",
"type" => "game",
"action" => "stTakeCards",
"transitions" => array( "startHand" => 30, "skip" => 30 )
),

// Trick

30 => array(
"name" => "newTrick",
"description" => "",
"type" => "game",
"action" => "stNewTrick",
"transitions" => array( "" => 31 )
),
31 => array(
"name" => "playerTurn",
"description" => clienttranslate('${actplayer} must play a card'),
"descriptionmyturn" => clienttranslate('${you} must play a card'),
"type" => "activeplayer",
"possibleactions" => array( "actPlayCard" ),
"transitions" => array( "playCard" => 32 )
),
32 => array(
"name" => "nextPlayer",
"description" => "",
"type" => "game",
"action" => "stNextPlayer",
"transitions" => array( "nextPlayer" => 31, "nextTrick" => 30, "endHand" => 40 )
),

// End of the hand (scoring, etc...)
40 => array(
"name" => "endHand",
"description" => "",
"type" => "game",
"action" => "stEndHand",
"transitions" => array( "nextHand" => 2, "endGame" => 99 )
),

);
</pre>

The full details on these fields are in [[Your_game_state_machine:_states.inc.php]].

But basically we have Player states, in which a human player has to perform an "action" by pressing some button in the UI or selecting some game item, which will trigger js handler, which will do an ajax call to the server.

To make it run we have to define all the handler functions that we referenced in states, which are - one function for state arguments argGiveCards, 4 functions for robot states (where the game performs some action)
and 1 function for player actions handling.
In Game.php, find 'Game state arguments' section and paste this in:
<pre>
function argGiveCards() {
return [];
}
</pre>

This normally passes some parameters to states, but we don't need anything yet. It's good to have a placeholder there anyway, so we can fix it later.
Important: even when it's a stub, this function must return an array not a scalar.

Let's do stubs for other functions, find the game state actions section in Game.php file and insert these (replace all st* method defined in template)
<pre>
function stNewHand() {
// Take back all cards (from any location => null) to deck
$this->cards->moveAllCardsInLocation(null, "deck");
$this->cards->shuffle('deck');
// Deal 13 cards to each players
// Create deck, shuffle it and give 13 initial cards
$players = $this->loadPlayersBasicInfos();
foreach ( $players as $player_id => $player ) {
$cards = $this->cards->pickCards(13, 'deck', $player_id);
// Notify player about his cards
$this->notify->player($player_id, 'newHand', '', array ('cards' => $cards ));
}
$this->setGameStateValue('alreadyPlayedHearts', 0);
$this->gamestate->nextState("");
}

function stNewTrick() {
// New trick: active the player who wins the last trick, or the player who own the club-2 card
// Reset trick color to 0 (= no color)
$this->setGameStateInitialValue('trickColor', 0);
$this->gamestate->nextState();
}

function stNextPlayer() {
// Active next player OR end the trick and go to the next trick OR end the hand
if ($this->cards->countCardInLocation('cardsontable') == 4) {
// This is the end of the trick
// Move all cards to "cardswon" of the given player
$best_value_player_id = $this->activeNextPlayer(); // TODO figure out winner of trick
$this->cards->moveAllCardsInLocation('cardsontable', 'cardswon', null, $best_value_player_id);

if ($this->cards->countCardInLocation('hand') == 0) {
// End of the hand
$this->gamestate->nextState("endHand");
} else {
// End of the trick
$this->gamestate->nextState("nextTrick");
}
} else {
// Standard case (not the end of the trick)
// => just active the next player
$player_id = $this->activeNextPlayer();
$this->giveExtraTime($player_id);
$this->gamestate->nextState('nextPlayer');
}
}

function stEndHand() {
$this->gamestate->nextState("nextHand");
}

</pre>
Important: All state actions game or player must end with state transition (or thrown exception). Also make sure it's ONLY one state transition,
if you accidentally fall through after state transition and do another one it will be a real mess and head scratching for long time.

Now find 'player actions' section and paste this code there (replace all existing act* functions)
<pre>
function actPlayCard(int $card_id) {
$player_id = $this->getActivePlayerId();
throw new \BgaUserException(clienttranslate('Not implemented: ${player_id} plays ${card_id}'), [
"player_id" => "$player_id",
"card_id" => $card_id,
]);

}
</pre>
We won't implement it yet but throw an exception which we will see if interaction is working properly

If your game is running you have to exit it. When we change state machine in the middle of the game usually it won't be good.

Now the game should start but it would not be any different than before because we have to implement actual interactions.
It's good to check if it's still working though (and if it was running before you have to exit because we changed state machine and normally it will break stuff).

NOTE: When you play a card, you will not yet get the "Not implemented" message. That is added in the next section.

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
<pre>
onUpdateActionButtons: function (stateName, args) {
console.log("onUpdateActionButtons: " + stateName, args);

if (this.isCurrentPlayerActive()) {
switch (stateName) {
case "playerTurn":
break;
}
}
},
</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.

Eventhough we can it ajax call the API now called "bgaPerformAction" and this is what you should be using.

So in .js code replace onPlayerHandSelectionChanged with
<pre>
onPlayerHandSelectionChanged : function() {
var items = this.playerHand.getSelectedItems();

if (items.length > 0) {
var action = 'actPlayCard';
if (this.checkAction(action, true)) {
// Can play a card
var card_id = items[0].id;
this.bgaPerformAction(action, {
card_id : card_id,
});

this.playerHand.unselectAll();
} else if (this.checkAction('actGiveCards')) {
// Can give cards => let the player select some cards
} else {
this.playerHand.unselectAll();
}
}
},
</pre>

Now when you click on card you should get a server response: Not implemented...

Lets implement it, in Game.php
<pre>

function actPlayCard(int $card_id) {
$player_id = $this->getActivePlayerId();
$this->cards->moveCard($card_id, 'cardsontable', $player_id);
// XXX check rules here
$currentCard = $this->cards->getCard($card_id);
// And notify
$this->notify->all('playCard', clienttranslate('${player_name} plays ${value_displayed} ${color_displayed}'), array (
'i18n' => array ('color_displayed','value_displayed' ),'card_id' => $card_id,'player_id' => $player_id,
'player_name' => $this->getActivePlayerName(),
'value' => $currentCard ['type_arg'],
'value_displayed' => self::$CARD_TYPES [$currentCard ['type_arg']] ['name'],
'color' => $currentCard ['type'],
'color_displayed' => self::$CARD_SUITS [$currentCard ['type']] ['name'] ));
// Next player
$this->gamestate->nextState('playCard');
}

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

<pre>
setupNotifications : function() {
console.log('notifications subscriptions setup');
// table of notif type to delay in milliseconds
const notifs = [
['newHand', 1],
['playCard', 100],
];

notifs.forEach((notif) => {
dojo.subscribe(notif[0], this, `notif_${notif[0]}`);
this.notifqueue.setSynchronous(notif[0], notif[1]);
});

},

notif_newHand : function(notif) {
// We received a new full hand of 13 cards.
this.playerHand.removeAll();

for ( var i in notif.args.cards) {
var card = notif.args.cards[i];
var color = card.type;
var value = card.type_arg;
this.playerHand.addToStockWithId(this.getCardUniqueId(color, value), card.id);
}
},

notif_playCard : function(notif) {
// Play a card on the table
this.playCardOnTable(notif.args.player_id, notif.args.color, notif.args.value, notif.args.card_id);
},
</pre>

Now it actually works through the server when you click on card - the move is recorded. If you test it now 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 we need to send notification about it
and have a handler for it

So in Game.php file add notification in stNextPlayer function after moveAllCardsInLocation call:

<pre>
// Notify
// 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 = $this->loadPlayersBasicInfos();
$this->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']
) );
$this->notify->all( 'giveAllCardsToPlayer','', array(
'player_id' => $best_value_player_id
) );
</pre>

And in .js file add 2 more notification handlers.

This is to subscribe in setupNotifications function
<pre>
const notifs = [
...
['trickWin', 1000],
['giveAllCardsToPlayer', 600],
];
</pre>

And these are handlers
<pre>
notif_trickWin : function(notif) {
// We do nothing here (just wait in order players can view the 4 cards played before they're gone.
},
notif_giveAllCardsToPlayer : function(notif) {
// Move all cards on table to given table, then destroy them
var winner_id = notif.args.player_id;
for ( var player_id in this.gamedatas.players) {
var anim = this.slideToObject('cardontable_' + player_id, 'overall_player_board_' + winner_id);
dojo.connect(anim, 'onEnd', function(node) {
dojo.destroy(node);
});
anim.play();
}
},
</pre>

So 'trickWin' notification does not do much except it will delay the processing of next notification by 1 second (1000 ms)
and it will log the message (that happens independently of what handler does).
<i>Note: if on the other hand you don't want to log but want to do something else, send an empty message</i>

Now after the trick you see all cards move towards the "player's stash".

==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 'trickColor' which we already conveniently created.

In Game.php file find the actPlayCard function and add this before notify functions
$currentTrickColor = $this->getGameStateValue( 'trickColor' ) ;
if( $currentTrickColor == 0 )
$this->setGameStateValue( 'trickColor', $currentCard['type'] );

This will make sure we remember the first suit being played, now to use it modify the stNextPlayer function to fix our TODO comment
<pre>
function stNextPlayer() {
// Active next player OR end the trick and go to the next trick OR end the hand
if ($this->cards->countCardInLocation('cardsontable') == 4) {
// This is the end of the trick
$cards_on_table = $this->cards->getCardsInLocation('cardsontable');
$best_value = 0;
$best_value_player_id = null;
$currentTrickColor = $this->getGameStateValue('trickColor');
foreach ( $cards_on_table as $card ) {
// Note: type = card color
if ($card ['type'] == $currentTrickColor) {
if ($best_value_player_id === null || $card ['type_arg'] > $best_value) {
$best_value_player_id = $card ['location_arg']; // Note: location_arg = player who played this card on table
$best_value = $card ['type_arg']; // Note: type_arg = value of the card
}
}
}

// Active this player => he's the one who starts the next trick
$this->gamestate->changeActivePlayer( $best_value_player_id );

// Move all cards to "cardswon" of the given player
$this->cards->moveAllCardsInLocation('cardsontable', 'cardswon', null, $best_value_player_id);

// Notify
// ... same code here 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, also
we want to show that in the log.
In addition scoring can be shown in [[Game_interface_logic:_yourgamename.js#Scoring_dialogs|Scoring Dialog]] using tableWindow notification, but it is a tutorial on its own and you can do it as homework (it is part of original heart game).

so in Game.php our stEndHand function will look like

<pre>
function stEndHand() {
// Count and score points, then end the game or go to the next hand.
$players = $this->loadPlayersBasicInfos();
// Gets all "hearts" + queen of spades

$player_to_points = array ();
foreach ( $players as $player_id => $player ) {
$player_to_points [$player_id] = 0;
}
$cards = $this->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) {
$this->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 ($this->playerScore->getMin() <= -100) {
// Trigger the end of the game !
$this->gamestate->nextState("endGame");
return;
}

$this->gamestate->nextState("nextHand");
}
</pre>

So it should more less work now, including end of game condition. Try to play it!

==Additional stuff==

The following things were not implemented and can add them yourself by looking at the code of original hearts game:

*Remove debug code from setupNewGame to deal cards, cards are now dealt in stNewHand state handler
*Rule checking and rule enforcements in actPlayCard function
*Start scoring with 100 points each and end when <= 0
*Fix scoring rules with Q of spades and 26 point reverse scoring
*First player one with 2 club
*Add progress handling
*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

2025-10-05T18:58:52Z

ShaharHarshuv: /* State Machine */ Add warning for out dated instructions

{{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]]).
* Know the rules for Hearts
* 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]

== 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. 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.
</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 full game can be found in your FTP home folder, after getting read-only access: https://en.doc.boardgamearena.com/First_steps_with_BGA_Studio#Set_up_dev_environment_ide,_editor_and_File_Sync

== 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://github.com/elaskavaia/bga-heartsla/blob/4b3a73eeb5acae961ade18473af119e8ce8d1a8f/img/cards.jpg hearts img/cards.jpg] into img/ folder of your project.
<blockquote>There are better quality deck of cards image at https://en.doc.boardgamearena.com/Common_board_game_elements_image_resources</blockquote>

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>
document.getElementById('game_play_area').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 (the image slightly obsolete, you may see more stuff there and different prompt).

[[File:Heartsla-tpl2.png]]

Now lets add a card into the hand, just so you can feel it. Edit the html string we inserted earlier and a playertablecard div inside a hand div
<pre>
...
<div id="myhand">
<div class="playertablecard"></div>
</div>
...
</pre>

Edit .css file
<pre>
.playertablecard {
display: inline-block;
position: relative;
margin-top: 5px;
width: 72px;
height: 96px;
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:

[[File:Heartsla-tpl3.png]]

Awesome! Now lets do the rest of layout.

Note: If you don't see the card a) check it was synced to remote folder b) force reload page

Let's complete the template string we created for the hand. You template should have this code, just leave it there
<pre>

// Example to add a div on the game area
document.getElementById("game_play_area").insertAdjacentHTML("beforeend",
`
<div id="player-tables"></div>
`
);
</pre>

Then change the following template code to this
<pre>
// Setting up player boards
var numPlayers = Object.keys(gamedatas.players).length;
Object.values(gamedatas.players).forEach((player, index) => {
document.getElementById("player-tables").insertAdjacentHTML(
"beforeend",
`
<div class="playertable whiteblock playertable_${DIRECTIONS[numPlayers][index]}">
<div class="playertablename" style="color:#${player.color};"><span class="dealer_token" id="dealer_token_p${player.id}">🃏 </span>${player.name}</div>
<div class="playertablecard" id="playertablecard_${player.id}"></div>
<div class="playertablename" id="hand_score_wrap_${player.id}"><span class="hand_score_label"></span> <span id="hand_score_${player.id}"></span></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
heartslav.js:68 Uncaught (in promise) ReferenceError: DIRECTIONS is not defined

For this new code to work, we need to add a constant at the beginning of the JS file, defining the expected position of each player (right after copyright comment):
<pre>
const DIRECTIONS = {
3: ['S', 'W', 'E'],
4: ['S', 'W', 'N', 'E'],
};
</pre>

Reload. If everything went well you should see this:

[[File:Hearts all rows.png|alt=Display a list of all players, with a dummy card in each position]]

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>
/** Table layout **/

#player-tables {
position: relative;
width: 710px;
height: 340px;
}

.playertablename {
font-weight: bold;
}

.playertable {
position: absolute;
text-align: center;
width: 180px;
height: 130px;
}

.playertable_N {
left: 50%;
top: 0px;
margin-left: -90px; /* half of 180 */
}
.playertable_S {
left: 50%;
bottom: 0px;
margin-left: -90px; /* half of 180 */
}
.playertable_W {
left: 0px;
top: 50%;
margin-top: -55px; /* half of 130 */
}
.playertable_E {
right: 0px;
top: 50%;
margin-top: -55px; /* half of 130 */
}
</pre>

Now you force Reload and you should see this:
[[File:Heartsla-tpl5.png]]

This is almost all we need for graphics and layout, there are few tweaks left there but lets do some more heavy lifting now.

<i>Note: if you did not see changes you may have not force reloaded, force means you use Ctrl+F5 or Cltr+Shift-R, if you don't "force" browser will use cached version of images! Which is not what you just changed</i>

<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 JS Stock ==

The BGA framework provides a few out of the box classes to deal with cards. The client side
contains a class called [[Stock]] and it can be used for any dynamic html "pieces" management that uses
common sprite images. 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 13x4 grid of images stitched together,
which is a very efficient way to transport images. So we will use the Stock class to mark up these images and create
"card" divs for us.

First, we need to add '''ebg/stock''' as a dependency in the .js file:
<pre>
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/stock" /// <==== HERE, don't forget comma before
],
</pre>

Then add this to the Javascript constructor, this will define size of our cards
<pre>
console.log('hearts constructor');
this.cardwidth = 72;
this.cardheight = 96;
</pre>

The stock is initialized in the Javascript "setup" method, after we have created the "myhand" element", like this:
<pre>
// TODO: Set up your game interface here, according to "gamedatas"

// Player hand
this.playerHand = new ebg.stock(); // new stock object for hand
this.playerHand.create( this, $('myhand'), this.cardwidth, this.cardheight );
</pre>

As parameters of the "create" method, we provided the width/height of an item (a card), and the container div "myhand" - which is an id of "div" element we have created before.

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

Here's how we tell stock what item types to display (add after .create):
<pre>
this.playerHand.image_items_per_row = 13; // 13 images per row

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

And add this function to the utilities section
<pre>
// Get card unique identifier based on its color and value
getCardUniqueId : function(color, value) {
return (color - 1) * 13 + (value - 2);
},
</pre>

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

Note: we need to generate a unique ID for each type of card based on its color and value. For that we create a function '''getCardUniqueId'''. The type is the unique identifier of the TYPE of the card, e.g., the queen of spades encoded as an integer. If our deck had 2 standard card decks we would have had 2 queens of spades; they would share the same type and the same image but would have different ids. NOTE: It's unfortunate that they named this '''getCardUniqueId'''; it should have been '''getCardUniqueType''', because it really isn't an id, but a TYPE of card. The type of the item should either be a reversible function of its properties (i.e., kind of suite * 13 + value) or just an enumerator described in material.inc.php. In this specific case it's a synthetic type id, which also the same as the number of the card in the sprite image (i.e., if you enumerate each image in sprite going left to right, then top to bottom).

Now let's add the 5 of Hearts to the player's hand just for fun (this code will go in setup method after types initialization):

<pre>
// 2 = hearts, 5 is 5, and 42 is the card id, which normally would come from db
this.playerHand.addToStockWithId( this.getCardUniqueId( 2, 5 ), 42 );
</pre>

This will add the card with id 42 and type 16 ( (2-1)*13+(5-2)=16 ).

Note that number 16 would not be something you can see in database, Deck database will have separate field for type and type_arg where type is suite and type_arg is number, so its not the same thing, but you can use same formula to convert. Number 42 on the other hand would be id field in database. But we get to database in the later section.

If you reload now you should see the 5 of hearts in "your hand".

You may see some weird graphics glitches - its because we did not remove our hack with background from .css yet. You can go to .css file now and remove line with comment "temp hack to see it".

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, after this.playerHand is initialised:

dojo.connect( this.playerHand, 'onChangeSelection', this, 'onPlayerHandSelectionChanged' );

Then find the Player's action comment section in .js file and add a handler after the comment:

<pre>
///////////////////////////////////////////////////
//// Player's action

onPlayerHandSelectionChanged: function () {
var items = this.playerHand.getSelectedItems();

if (items.length > 0) {
if (this.checkAction("actPlayCard", true)) {
// Can play a card

var card_id = items[0].id;
console.log("on playCard " + card_id);

this.playerHand.unselectAll();
} else if (this.checkAction("actGiveCards")) {
// Can give cards => let the player select some cards
} else {
this.playerHand.unselectAll();
}
}
},
</pre>

''Note : If you already have an example handler <code>onCardClick: function( card_id )</code>, go ahead and remove that handler, it is a duplicate of what we are implementing in this tutorial and may cause issues later on.''

The function name of the handler is 4th parameter of the dojo.connect function. Make sure you spell it correctly or there will be unpredictable effects.

Now if you reload, open the Javascript Console (F12), and then click on the card in My Hand, you should see:
on playCard 42
printed on the console

''Note : You need to be the active player to have rights to play a card and so log your message in the console''

== 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 ====
To modify the schema, first exit your existing game(s). Open '''dbmodel.sql''' file and uncomment the card table creation.

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

This is the "card" table which will be managed by the Deck php class.

In addition we want a little piece of information in the players table:

-- add info about first player
ALTER TABLE `player` ADD `player_first` BOOLEAN NOT NULL DEFAULT '0';

Not sure why they put this into the player table, as we could use a global db variable to hold first player as easily.
But I am just following the existing code more-or-less. It is not recommended to modify player table in general.

=== Game State Variables ===
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>
parent::__construct();
$this->initGameStateLabels(
[
"currentHandType" => 10,
"trickColor" => 11,
"alreadyPlayedHearts" => 12,
]
);;

$this->cards = $this->deckFactory->createDeck('card');
</pre>

If you see errors in IDE its because we also have to declared "cards" as class member, add ''protected $cards;'' before the contructor.

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:

*"trickColor": numbers from 1 to 4 that map to card suit (not sure why it's called color; maybe it's a translation from French);
*"alreadyPlayedHearts": a boolean flag (0 or 1) indicating whether somebody used hearts on the trick;
*"currentHandType": stores the value to indicate who to give cards to during exchange.

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>

Since we changed the db, 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>

Code Rev [https://github.com/elaskavaia/bga-heartsla/tree/acd1926a6c09dc9afd0752cb6b78eef17c5dfe5c]

=== 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 "TODO: Setup the initial game situation here" comment.
<pre>
// Init global values with their initial values

// Note: hand types: 0 = give 3 cards to player on the left
// 1 = give 3 cards to player on the right
// 2 = give 3 cards to player opposite
// 3 = keep cards
$this->setGameStateInitialValue('currentHandType', 0);

// Set current trick color to zero (= no trick color)
$this->setGameStateInitialValue('trickColor', 0);

// Mark if we already played hearts during this hand
$this->setGameStateInitialValue('alreadyPlayedHearts', 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.
<pre>
// Create cards
$cards = [];
foreach (self::$CARD_SUITS as $suit => $suit_info) {
// spade, heart, diamond, club
foreach (self::$CARD_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 ''self:$CARD_SUITS''.
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 (if you already have ''self::$CARD_TYPES'', replace it)

<pre>
elf::$CARD_SUITS = [
1 => [
'name' => clienttranslate('Spade'),
],
2 => [
'name' => clienttranslate('Heart'),
],
3 => [
'name' => clienttranslate('Club'),
],
4 => [
'name' => clienttranslate('Diamond'),
]
];

self::$CARD_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 declared these fields in the class
private static array $CARD_SUITS;
private static array $CARD_TYPES;

==== 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) {
$cards = $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', $current_player_id);

// 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 .js file in the setup function (which is the receiver of getAllDatas) replace our hack of putting 5 of Hearts directly into the hand with:

<pre>
// Cards in player's hand
for (var i in this.gamedatas.hand) {
var card = this.gamedatas.hand[i];
var color = card.type;
var value = card.type_arg;
this.playerHand.addToStockWithId(this.getCardUniqueId(color, value), card.id);
}
</pre>

At this point, you could start a new game and each player should see their hand!

=== Cards on Table ===
To the setup method, add:
// Cards played on table
for (i in this.gamedatas.cardsontable) {
var card = this.gamedatas.cardsontable[i];
var color = card.type;
var value = card.type_arg;
var player_id = card.location_arg;
this.playCardOnTable(player_id, color, value, card.id);
}
Add the '''playCardOnTable''' function in the "utilities" section.

<pre>
playCardOnTable : function(player_id, color, value, card_id) {
// player_id => direction
this.addTableCard(value, color, player_id, player_id);

if (player_id != this.player_id) {
// Some opponent played a card
// Move card from player panel
this.placeOnObject('cardontable_' + player_id, 'overall_player_board_' + player_id);
} else {
// You played a card. If it exists in your hand, move card from there and remove
// corresponding item

if ($('myhand_item_' + card_id)) {
this.placeOnObject('cardontable_' + player_id, 'myhand_item_' + card_id);
this.playerHand.removeFromStockById(card_id);
}
}

// In any case: move it to its final destination
this.slideToObject('cardontable_' + player_id, 'playertablecard_' + player_id).play();
},
</pre>

For this to work we also need to define the addTableCard
<pre>
addTableCard(value, color, card_player_id, playerTableId) {
const x = value - 2;
const y = color - 1;
document.getElementById('playertablecard_' + playerTableId).insertAdjacentHTML('beforeend', `
<div class="card cardontable" id="cardontable_${card_player_id}" style="background-position:-${x}00% -${y}00%"></div>
`);
},
</pre>

What this does is basically create another card object, because if it is not our card it's not in our hand (Stock) so
we have to create it out of thin air. Now we have an object with an id of 'cardontable_' + player_id. Depending
on who is playing it we either place it on the player miniboard or in hand (and remove it from hand stock). Then we animate the card move.

We also should fix our .css file now to add style for cardontable and REMOVE background for playertablecard which really is a placeholder div and not a card. (Don't miss the remove step; it will be all screwy if you do!)

<pre>
.playertablecard {
display: inline-block;
position: relative;
margin-top: 5px;
width: 72px;
height: 96px;
/* we remove background-image here */
}

/*** cards on table ***/

.cardontable {
position: absolute;
width: 72px;
height: 96px;
background-image: url('img/cards.jpg');
}
</pre>

Next, we will hook-up clicking on card and test if our ''playCardOnTable'' works.

Find ''onPlayerHandSelectionChanged'' function in the JS file, we should have logging there like ''console.log("on playCard "+card_id);''
So after that insert this (Note: this code is for testing we will replace it with server interaction after we test it.):
<pre>
console.log("on playCard " + card_id);
// type is (color - 1) * 13 + (value - 2)
var type = items[0].type;
var color = Math.floor(type / 13) + 1;
var value = (type % 13) + 2;

this.playCardOnTable(this.player_id, color, value, card_id);
</pre>
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]]

Code Rev [https://github.com/elaskavaia/bga-heartsla/tree/0ed80e254a6d0c29f267b308d1c2016db90fd4f6]

==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. 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 is selected who will start a new trick ("NewTrick")
*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) ("NextHand")



The state handling spread across multiple files, so you have to make sure all pieces are connected together.
The state machine states.php defines all the states, and function handlers on php side in a form of string,
and if any of these functions are not implemented it would be very hard to debug because it will break in random places.

So .states.php (remove all template states and replace with these)

<pre>
$machinestates = array(
/// New hand
2 => array(
"name" => "newHand",
"description" => "",
"type" => "game",
"action" => "stNewHand",
"updateGameProgression" => true,
"transitions" => array( "" => 30 )
),

21 => array(
"name" => "giveCards",
"description" => clienttranslate('Some players must choose 3 cards to give to ${direction}'),
"descriptionmyturn" => clienttranslate('${you} must choose 3 cards to give to ${direction}'),
"type" => "multipleactiveplayer",
"action" => "stGiveCards",
"args" => "argGiveCards",
"possibleactions" => array( "actGiveCards" ),
"transitions" => array( "giveCards" => 22, "skip" => 22 )
),

22 => array(
"name" => "takeCards",
"description" => "",
"type" => "game",
"action" => "stTakeCards",
"transitions" => array( "startHand" => 30, "skip" => 30 )
),

// Trick

30 => array(
"name" => "newTrick",
"description" => "",
"type" => "game",
"action" => "stNewTrick",
"transitions" => array( "" => 31 )
),
31 => array(
"name" => "playerTurn",
"description" => clienttranslate('${actplayer} must play a card'),
"descriptionmyturn" => clienttranslate('${you} must play a card'),
"type" => "activeplayer",
"possibleactions" => array( "actPlayCard" ),
"transitions" => array( "playCard" => 32 )
),
32 => array(
"name" => "nextPlayer",
"description" => "",
"type" => "game",
"action" => "stNextPlayer",
"transitions" => array( "nextPlayer" => 31, "nextTrick" => 30, "endHand" => 40 )
),

// End of the hand (scoring, etc...)
40 => array(
"name" => "endHand",
"description" => "",
"type" => "game",
"action" => "stEndHand",
"transitions" => array( "nextHand" => 2, "endGame" => 99 )
),

);
</pre>

The full details on these fields are in [[Your_game_state_machine:_states.inc.php]].

But basically we have Player states, in which a human player has to perform an "action" by pressing some button in the UI or selecting some game item, which will trigger js handler, which will do an ajax call to the server.

To make it run we have to define all the handler functions that we referenced in states, which are - one function for state arguments argGiveCards, 4 functions for robot states (where the game performs some action)
and 1 function for player actions handling.
In Game.php, find 'Game state arguments' section and paste this in:
<pre>
function argGiveCards() {
return [];
}
</pre>

This normally passes some parameters to states, but we don't need anything yet. It's good to have a placeholder there anyway, so we can fix it later.
Important: even when it's a stub, this function must return an array not a scalar.

Let's do stubs for other functions, find the game state actions section in Game.php file and insert these (replace all st* method defined in template)
<pre>
function stNewHand() {
// Take back all cards (from any location => null) to deck
$this->cards->moveAllCardsInLocation(null, "deck");
$this->cards->shuffle('deck');
// Deal 13 cards to each players
// Create deck, shuffle it and give 13 initial cards
$players = $this->loadPlayersBasicInfos();
foreach ( $players as $player_id => $player ) {
$cards = $this->cards->pickCards(13, 'deck', $player_id);
// Notify player about his cards
$this->notify->player($player_id, 'newHand', '', array ('cards' => $cards ));
}
$this->setGameStateValue('alreadyPlayedHearts', 0);
$this->gamestate->nextState("");
}

function stNewTrick() {
// New trick: active the player who wins the last trick, or the player who own the club-2 card
// Reset trick color to 0 (= no color)
$this->setGameStateInitialValue('trickColor', 0);
$this->gamestate->nextState();
}

function stNextPlayer() {
// Active next player OR end the trick and go to the next trick OR end the hand
if ($this->cards->countCardInLocation('cardsontable') == 4) {
// This is the end of the trick
// Move all cards to "cardswon" of the given player
$best_value_player_id = $this->activeNextPlayer(); // TODO figure out winner of trick
$this->cards->moveAllCardsInLocation('cardsontable', 'cardswon', null, $best_value_player_id);

if ($this->cards->countCardInLocation('hand') == 0) {
// End of the hand
$this->gamestate->nextState("endHand");
} else {
// End of the trick
$this->gamestate->nextState("nextTrick");
}
} else {
// Standard case (not the end of the trick)
// => just active the next player
$player_id = $this->activeNextPlayer();
$this->giveExtraTime($player_id);
$this->gamestate->nextState('nextPlayer');
}
}

function stEndHand() {
$this->gamestate->nextState("nextHand");
}

</pre>
Important: All state actions game or player must end with state transition (or thrown exception). Also make sure it's ONLY one state transition,
if you accidentally fall through after state transition and do another one it will be a real mess and head scratching for long time.

Now find 'player actions' section and paste this code there (replace all existing act* functions)
<pre>
function actPlayCard(int $card_id) {
$player_id = $this->getActivePlayerId();
throw new \BgaUserException(clienttranslate('Not implemented: ${player_id} plays ${card_id}'), [
"player_id" => "$player_id",
"card_id" => $card_id,
]);

}
</pre>
We won't implement it yet but throw an exception which we will see if interaction is working properly

If your game is running you have to exit it. When we change state machine in the middle of the game usually it won't be good.

Now the game should start but it would not be any different than before because we have to implement actual interactions.
It's good to check if it's still working though (and if it was running before you have to exit because we changed state machine and normally it will break stuff).

NOTE: When you play a card, you will not yet get the "Not implemented" message. That is added in the next section.

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
<pre>
onUpdateActionButtons: function (stateName, args) {
console.log("onUpdateActionButtons: " + stateName, args);

if (this.isCurrentPlayerActive()) {
switch (stateName) {
case "playerTurn":
break;
}
}
},
</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.

Eventhough we can it ajax call the API now called "bgaPerformAction" and this is what you should be using.

So in .js code replace onPlayerHandSelectionChanged with
<pre>
onPlayerHandSelectionChanged : function() {
var items = this.playerHand.getSelectedItems();

if (items.length > 0) {
var action = 'actPlayCard';
if (this.checkAction(action, true)) {
// Can play a card
var card_id = items[0].id;
this.bgaPerformAction(action, {
card_id : card_id,
});

this.playerHand.unselectAll();
} else if (this.checkAction('actGiveCards')) {
// Can give cards => let the player select some cards
} else {
this.playerHand.unselectAll();
}
}
},
</pre>

Now when you click on card you should get a server response: Not implemented...

Lets implement it, in Game.php
<pre>

function actPlayCard(int $card_id) {
$player_id = $this->getActivePlayerId();
$this->cards->moveCard($card_id, 'cardsontable', $player_id);
// XXX check rules here
$currentCard = $this->cards->getCard($card_id);
// And notify
$this->notify->all('playCard', clienttranslate('${player_name} plays ${value_displayed} ${color_displayed}'), array (
'i18n' => array ('color_displayed','value_displayed' ),'card_id' => $card_id,'player_id' => $player_id,
'player_name' => $this->getActivePlayerName(),
'value' => $currentCard ['type_arg'],
'value_displayed' => self::$CARD_TYPES [$currentCard ['type_arg']] ['name'],
'color' => $currentCard ['type'],
'color_displayed' => self::$CARD_SUITS [$currentCard ['type']] ['name'] ));
// Next player
$this->gamestate->nextState('playCard');
}

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

<pre>
setupNotifications : function() {
console.log('notifications subscriptions setup');
// table of notif type to delay in milliseconds
const notifs = [
['newHand', 1],
['playCard', 100],
];

notifs.forEach((notif) => {
dojo.subscribe(notif[0], this, `notif_${notif[0]}`);
this.notifqueue.setSynchronous(notif[0], notif[1]);
});

},

notif_newHand : function(notif) {
// We received a new full hand of 13 cards.
this.playerHand.removeAll();

for ( var i in notif.args.cards) {
var card = notif.args.cards[i];
var color = card.type;
var value = card.type_arg;
this.playerHand.addToStockWithId(this.getCardUniqueId(color, value), card.id);
}
},

notif_playCard : function(notif) {
// Play a card on the table
this.playCardOnTable(notif.args.player_id, notif.args.color, notif.args.value, notif.args.card_id);
},
</pre>

Now it actually works through the server when you click on card - the move is recorded. If you test it now 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 we need to send notification about it
and have a handler for it

So in Game.php file add notification in stNextPlayer function after moveAllCardsInLocation call:

<pre>
// Notify
// 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 = $this->loadPlayersBasicInfos();
$this->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']
) );
$this->notify->all( 'giveAllCardsToPlayer','', array(
'player_id' => $best_value_player_id
) );
</pre>

And in .js file add 2 more notification handlers.

This is to subscribe in setupNotifications function
<pre>
const notifs = [
...
['trickWin', 1000],
['giveAllCardsToPlayer', 600],
];
</pre>

And these are handlers
<pre>
notif_trickWin : function(notif) {
// We do nothing here (just wait in order players can view the 4 cards played before they're gone.
},
notif_giveAllCardsToPlayer : function(notif) {
// Move all cards on table to given table, then destroy them
var winner_id = notif.args.player_id;
for ( var player_id in this.gamedatas.players) {
var anim = this.slideToObject('cardontable_' + player_id, 'overall_player_board_' + winner_id);
dojo.connect(anim, 'onEnd', function(node) {
dojo.destroy(node);
});
anim.play();
}
},
</pre>

So 'trickWin' notification does not do much except it will delay the processing of next notification by 1 second (1000 ms)
and it will log the message (that happens independently of what handler does).
<i>Note: if on the other hand you don't want to log but want to do something else, send an empty message</i>

Now after the trick you see all cards move towards the "player's stash".

==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 'trickColor' which we already conveniently created.

In Game.php file find the actPlayCard function and add this before notify functions
$currentTrickColor = $this->getGameStateValue( 'trickColor' ) ;
if( $currentTrickColor == 0 )
$this->setGameStateValue( 'trickColor', $currentCard['type'] );

This will make sure we remember the first suit being played, now to use it modify the stNextPlayer function to fix our TODO comment
<pre>
function stNextPlayer() {
// Active next player OR end the trick and go to the next trick OR end the hand
if ($this->cards->countCardInLocation('cardsontable') == 4) {
// This is the end of the trick
$cards_on_table = $this->cards->getCardsInLocation('cardsontable');
$best_value = 0;
$best_value_player_id = null;
$currentTrickColor = $this->getGameStateValue('trickColor');
foreach ( $cards_on_table as $card ) {
// Note: type = card color
if ($card ['type'] == $currentTrickColor) {
if ($best_value_player_id === null || $card ['type_arg'] > $best_value) {
$best_value_player_id = $card ['location_arg']; // Note: location_arg = player who played this card on table
$best_value = $card ['type_arg']; // Note: type_arg = value of the card
}
}
}

// Active this player => he's the one who starts the next trick
$this->gamestate->changeActivePlayer( $best_value_player_id );

// Move all cards to "cardswon" of the given player
$this->cards->moveAllCardsInLocation('cardsontable', 'cardswon', null, $best_value_player_id);

// Notify
// ... same code here 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, also
we want to show that in the log.
In addition scoring can be shown in [[Game_interface_logic:_yourgamename.js#Scoring_dialogs|Scoring Dialog]] using tableWindow notification, but it is a tutorial on its own and you can do it as homework (it is part of original heart game).

so in Game.php our stEndHand function will look like

<pre>
function stEndHand() {
// Count and score points, then end the game or go to the next hand.
$players = $this->loadPlayersBasicInfos();
// Gets all "hearts" + queen of spades

$player_to_points = array ();
foreach ( $players as $player_id => $player ) {
$player_to_points [$player_id] = 0;
}
$cards = $this->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) {
$this->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 ($this->playerScore->getMin() <= -100) {
// Trigger the end of the game !
$this->gamestate->nextState("endGame");
return;
}

$this->gamestate->nextState("nextHand");
}
</pre>

So it should more less work now, including end of game condition. Try to play it!

==Additional stuff==

The following things were not implemented and can add them yourself by looking at the code of original hearts game:

*Remove debug code from setupNewGame to deal cards, cards are now dealt in stNewHand state handler
*Rule checking and rule enforcements in actPlayCard function
*Start scoring with 100 points each and end when <= 0
*Fix scoring rules with Q of spades and 26 point reverse scoring
*First player one with 2 club
*Add progress handling
*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 reversi

2025-10-05T18:58:19Z

ShaharHarshuv: /* The game state machine */

If you want to use TypeScript, you can '''check out an updated version''' of the [[BGA Type Safe Template: Reversi|Reversi Tutorial]] which uses the [[BGA Type Safe Template]]. '''Important note: BGA Type Safe Template is a project created by a developer that is not part of the BGA team, and is outdated. This is currently not officially supported by BGA.''' {{Studio_Framework_Navigation}}

== Introduction ==

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

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

== Create your first game ==

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

With the initial skeleton of code provided in your project, you can already start a game from the BGA Studio:
* Go to your [https://studio.boardgamearena.com/controlpanel studio Control panel], then Manage games and select your initial project. ''Note: there are warnings displayed about a missing BGG_ID and presentation text. You can ignore that for now.''
* Click the Play link next to your project name. This will open the Play page and offer to create a new table for your project. ''Optional: click the Heart icon to add your project to your favorite games list.''
* On the Play page, on the top of the page, make sure that your settings are "Simple game", "Real time" and "Manual".
* Click "Create table" to create a table of your project.
* For now, we are going to work with one player only, so use the (-) button to set the number of players to 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 "Game Information" section, click "Reload game informations".
* Finally, refresh the project page in your browser (usually CTRL-F5).

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

Sometimes the cache will keep your changes from showing. Since this is a possibility, it will be useful to know how to bypass the cache. To do so you may manually clear cache or use a shortcut to refresh and ignore the cached version of the page. Here's how

====== Windows ======
Chrome, Firefox, or Edge: Press <code>Ctrl+F5</code> or <code>Shift+F5</code> or <code>Ctrl+Shift+R</code>

====== Mac ======
Chrome or Firefox: Press <code>Shift+Command+R</code>

Safari for Mac: Press <code>Command+Option+E</code> to empty the cache, then hold down Shift and click Reload in the toolbar

== Make it look like Reversi ==

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

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

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

[[File:Board.jpg]]

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

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

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

<pre>
this.getGameAreaElement().insertAdjacentHTML('beforeend', `
<div id="board">
</div>
`);
</pre>

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

'''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, js template to the tpl, utility method in the js, adjusted the php file, and added the token to the board in the js file.

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

[[File:tokens.png]]

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

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

==== Style the Tokens in .css file ====
<pre>
.disc {
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>reversi.js</code> file) that will make a token appear on the board, using this template. Add under the section <code>//// Utility methods</code>:

<pre>
addDiscOnBoard: async function( x, y, 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.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 = array( "ffffff", "000000" );
</pre>

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

=== Test the Token ===
Now, to test if everything works fine

==== <code>addTokenOnBoard()</code> in .js file to Test ====
In <code>reversi.js</code>, in <code>setup: function</code>, under the code we added to generate the squares.
this.addDiscOnBoard(2, 2, this.player_id, 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(5) unsigned NOT NULL,
`board_y` smallint(5) unsigned NOT NULL,
`board_player` int(10) unsigned DEFAULT NULL,
PRIMARY KEY (`board_x`,`board_y`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
</pre>

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

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

Start a new game and verify a table is created.

== Setup the initial game position ==

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

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

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

$sql_values[] = "('$x','$y',$token_value)";
}
}
$sql .= implode( ',', $sql_values );
$this->DbQuery( $sql );
</pre>

==== Board Initialization Explanation ====

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

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

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

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

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

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

Next, you 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.player_id);</code>

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

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

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

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

[[File:reversi5.jpg]]

It starts to feel like Reversi here...

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

'''NextPlayer.php:'''
<pre>
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/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 argPlayerTurn(int $activePlayerId): array
{
return [
'possibleMoves' => $this->game->getPossibleMoves($activePlayerId)
];
}
</pre>

<strong>Note:</strong> after this modification you will need to modify the <code>onUpdateActionButtons</code> function in your javascript to remove the references to <code>playableCardsIds</code> in order to launch a game, there will be javascript errors in the console as the code will blow up when it tries to loop over that array.

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

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

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

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

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

<pre>
updatePossibleMoves: function( possibleMoves )
{
// Remove current possible moves
document.querySelectorAll('.possibleMove').forEach(div => div.classList.remove('possibleMove'));

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

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

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

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

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

And here we are:

[[File:reversi8.jpg.jpg]]

==Let's play==

From now, it's better to restart a game with 2 players, because we are going to implement a complete Reversi turn. The summary of what we are going to do is:
*When we click on a 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: function( evt )
{
// Stop this event propagation
evt.preventDefault();
evt.stopPropagation();

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

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

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

What we do here is:
*We stop the propagation of the Javascript <code>onclick</code> event. Otherwise, it can lead to random behavior so it's always a good idea.
*We get the x/y coordinates of the square by using <code>evt.currentTarget.id</code>
* We check that clicked square has the <code>possibleMove</code> class, otherwise we know for sure that we can't play there.
*Finally, we make a call to the server using BGA <code>bgaPerformAction</code> method with argument x and y. This call will check that <code>actPlayDisc</code> action is possible, according to current game state (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->getBoard();
$turnedOverDiscs = $this->game->getTurnedOverDiscs( $x, $y, $activePlayerId, $board );

if( count( $turnedOverDiscs ) === 0 ) {
throw new \BgaSystemException("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

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

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

$this->game->DbQuery( $sql );
</pre>

we manage game statistics:
<pre>
// Statistics
$this->game->incStat( count( $turnedOverDiscs ), "turnedOver", $player_id );
if( ($x==1 && $y==1) || ($x==8 && $y==1) || ($x==1 && $y==8) || ($x==8 && $y==8) )
$this->game->incStat( 1, 'discPlayedOnCorner', $activePlayerId );
else if( $x==1 || $x==8 || $y==1 || $y==8 )
$this->game->incStat( 1, 'discPlayedOnBorder', $activePlayerId );
else if( $x>=3 && $x<=6 && $y>=3 && $y<=6 )
$this->game->incStat( 1, 'discPlayedOnCenter', $activePlayerId );
</pre>

Notify the turned discs:
<pre>
// Notify
$this->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->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 = (int)$this->game->getUniqueValueFromDB("SELECT COUNT(*) FROM `board` WHERE `board_player` = $playerId");
$this->playerScore->set($playerId, $tokens); // this will update the JS counter automatically
}
</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->activeNextPlayer());

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

if( ! isset( $player_to_discs[ null ] ) )
{
// Index 0 has not been set => there's no more free place on the board !
// => end of the game
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->getPossibleMoves( $player_id );
if( count( $possibleMoves ) == 0 )
{

// This player can't play
// Can his opponent play ?
$opponent_id = (int)$this->getUniqueValueFromDb( "SELECT player_id FROM player WHERE player_id!='$player_id' " );
if( count( $this->getPossibleMoves( $opponent_id ) ) == 0 )
{
// Nobody can move => end of the game
return ST_END_GAME;
}
else
{
// => pass his turn
return NextPlayer::class;
}
}
else
{
// This player can play. Give him some extra time
$this->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>reversi.js</code>, we tell BGA to listen to notifications we will add later (<code>playDisc</code> and <code>turnOverDiscs</code>) using promise-based notifications:

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

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

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

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

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

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

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

<pre>
animateTurnOverDisc: async function(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.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.wait(500); // for the flip animation removal to finish
},

notif_turnOverDiscs: async function( args )
{

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

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

}
</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->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) {
$count = 0;
while (intval($this->gamestate->getCurrentMainStateId()) < 99 && $count < $moves) {
$count++;
foreach($this->gamestate->getActivePlayerList() as $playerId) {
$playerId = (int)$playerId;
$this->gamestate->runStateClassZombie($this->gamestate->getCurrentState($playerId), $playerId);
}
}
}

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

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

2025-10-05T05:23:14Z

ShaharHarshuv: /* Full game model synchronization */

{{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]]).
* Know the rules for Hearts
* 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]

== 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. 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.
</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 full game can be found in your FTP home folder, after getting read-only access: https://en.doc.boardgamearena.com/First_steps_with_BGA_Studio#Set_up_dev_environment_ide,_editor_and_File_Sync

== 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://github.com/elaskavaia/bga-heartsla/blob/4b3a73eeb5acae961ade18473af119e8ce8d1a8f/img/cards.jpg hearts img/cards.jpg] into img/ folder of your project.
<blockquote>There are better quality deck of cards image at https://en.doc.boardgamearena.com/Common_board_game_elements_image_resources</blockquote>

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>
document.getElementById('game_play_area').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 (the image slightly obsolete, you may see more stuff there and different prompt).

[[File:Heartsla-tpl2.png]]

Now lets add a card into the hand, just so you can feel it. Edit the html string we inserted earlier and a playertablecard div inside a hand div
<pre>
...
<div id="myhand">
<div class="playertablecard"></div>
</div>
...
</pre>

Edit .css file
<pre>
.playertablecard {
display: inline-block;
position: relative;
margin-top: 5px;
width: 72px;
height: 96px;
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:

[[File:Heartsla-tpl3.png]]

Awesome! Now lets do the rest of layout.

Note: If you don't see the card a) check it was synced to remote folder b) force reload page

Let's complete the template string we created for the hand. You template should have this code, just leave it there
<pre>

// Example to add a div on the game area
document.getElementById("game_play_area").insertAdjacentHTML("beforeend",
`
<div id="player-tables"></div>
`
);
</pre>

Then change the following template code to this
<pre>
// Setting up player boards
var numPlayers = Object.keys(gamedatas.players).length;
Object.values(gamedatas.players).forEach((player, index) => {
document.getElementById("player-tables").insertAdjacentHTML(
"beforeend",
`
<div class="playertable whiteblock playertable_${DIRECTIONS[numPlayers][index]}">
<div class="playertablename" style="color:#${player.color};"><span class="dealer_token" id="dealer_token_p${player.id}">🃏 </span>${player.name}</div>
<div class="playertablecard" id="playertablecard_${player.id}"></div>
<div class="playertablename" id="hand_score_wrap_${player.id}"><span class="hand_score_label"></span> <span id="hand_score_${player.id}"></span></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
heartslav.js:68 Uncaught (in promise) ReferenceError: DIRECTIONS is not defined

For this new code to work, we need to add a constant at the beginning of the JS file, defining the expected position of each player (right after copyright comment):
<pre>
const DIRECTIONS = {
3: ['S', 'W', 'E'],
4: ['S', 'W', 'N', 'E'],
};
</pre>

Reload. If everything went well you should see this:

[[File:Hearts all rows.png|alt=Display a list of all players, with a dummy card in each position]]

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>
/** Table layout **/

#player-tables {
position: relative;
width: 710px;
height: 340px;
}

.playertablename {
font-weight: bold;
}

.playertable {
position: absolute;
text-align: center;
width: 180px;
height: 130px;
}

.playertable_N {
left: 50%;
top: 0px;
margin-left: -90px; /* half of 180 */
}
.playertable_S {
left: 50%;
bottom: 0px;
margin-left: -90px; /* half of 180 */
}
.playertable_W {
left: 0px;
top: 50%;
margin-top: -55px; /* half of 130 */
}
.playertable_E {
right: 0px;
top: 50%;
margin-top: -55px; /* half of 130 */
}
</pre>

Now you force Reload and you should see this:
[[File:Heartsla-tpl5.png]]

This is almost all we need for graphics and layout, there are few tweaks left there but lets do some more heavy lifting now.

<i>Note: if you did not see changes you may have not force reloaded, force means you use Ctrl+F5 or Cltr+Shift-R, if you don't "force" browser will use cached version of images! Which is not what you just changed</i>

<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 JS Stock ==

The BGA framework provides a few out of the box classes to deal with cards. The client side
contains a class called [[Stock]] and it can be used for any dynamic html "pieces" management that uses
common sprite images. 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 13x4 grid of images stitched together,
which is a very efficient way to transport images. So we will use the Stock class to mark up these images and create
"card" divs for us.

First, we need to add '''ebg/stock''' as a dependency in the .js file:
<pre>
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/stock" /// <==== HERE, don't forget comma before
],
</pre>

Then add this to the Javascript constructor, this will define size of our cards
<pre>
console.log('hearts constructor');
this.cardwidth = 72;
this.cardheight = 96;
</pre>

The stock is initialized in the Javascript "setup" method, after we have created the "myhand" element", like this:
<pre>
// TODO: Set up your game interface here, according to "gamedatas"

// Player hand
this.playerHand = new ebg.stock(); // new stock object for hand
this.playerHand.create( this, $('myhand'), this.cardwidth, this.cardheight );
</pre>

As parameters of the "create" method, we provided the width/height of an item (a card), and the container div "myhand" - which is an id of "div" element we have created before.

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

Here's how we tell stock what item types to display (add after .create):
<pre>
this.playerHand.image_items_per_row = 13; // 13 images per row

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

And add this function to the utilities section
<pre>
// Get card unique identifier based on its color and value
getCardUniqueId : function(color, value) {
return (color - 1) * 13 + (value - 2);
},
</pre>

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

Note: we need to generate a unique ID for each type of card based on its color and value. For that we create a function '''getCardUniqueId'''. The type is the unique identifier of the TYPE of the card, e.g., the queen of spades encoded as an integer. If our deck had 2 standard card decks we would have had 2 queens of spades; they would share the same type and the same image but would have different ids. NOTE: It's unfortunate that they named this '''getCardUniqueId'''; it should have been '''getCardUniqueType''', because it really isn't an id, but a TYPE of card. The type of the item should either be a reversible function of its properties (i.e., kind of suite * 13 + value) or just an enumerator described in material.inc.php. In this specific case it's a synthetic type id, which also the same as the number of the card in the sprite image (i.e., if you enumerate each image in sprite going left to right, then top to bottom).

Now let's add the 5 of Hearts to the player's hand just for fun (this code will go in setup method after types initialization):

<pre>
// 2 = hearts, 5 is 5, and 42 is the card id, which normally would come from db
this.playerHand.addToStockWithId( this.getCardUniqueId( 2, 5 ), 42 );
</pre>

This will add the card with id 42 and type 16 ( (2-1)*13+(5-2)=16 ).

Note that number 16 would not be something you can see in database, Deck database will have separate field for type and type_arg where type is suite and type_arg is number, so its not the same thing, but you can use same formula to convert. Number 42 on the other hand would be id field in database. But we get to database in the later section.

If you reload now you should see the 5 of hearts in "your hand".

You may see some weird graphics glitches - its because we did not remove our hack with background from .css yet. You can go to .css file now and remove line with comment "temp hack to see it".

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, after this.playerHand is initialised:

dojo.connect( this.playerHand, 'onChangeSelection', this, 'onPlayerHandSelectionChanged' );

Then find the Player's action comment section in .js file and add a handler after the comment:

<pre>
///////////////////////////////////////////////////
//// Player's action

onPlayerHandSelectionChanged: function () {
var items = this.playerHand.getSelectedItems();

if (items.length > 0) {
if (this.checkAction("actPlayCard", true)) {
// Can play a card

var card_id = items[0].id;
console.log("on playCard " + card_id);

this.playerHand.unselectAll();
} else if (this.checkAction("actGiveCards")) {
// Can give cards => let the player select some cards
} else {
this.playerHand.unselectAll();
}
}
},
</pre>

''Note : If you already have an example handler <code>onCardClick: function( card_id )</code>, go ahead and remove that handler, it is a duplicate of what we are implementing in this tutorial and may cause issues later on.''

The function name of the handler is 4th parameter of the dojo.connect function. Make sure you spell it correctly or there will be unpredictable effects.

Now if you reload, open the Javascript Console (F12), and then click on the card in My Hand, you should see:
on playCard 42
printed on the console

''Note : You need to be the active player to have rights to play a card and so log your message in the console''

== 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 ====
To modify the schema, first exit your existing game(s). Open '''dbmodel.sql''' file and uncomment the card table creation.

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

This is the "card" table which will be managed by the Deck php class.

In addition we want a little piece of information in the players table:

-- add info about first player
ALTER TABLE `player` ADD `player_first` BOOLEAN NOT NULL DEFAULT '0';

Not sure why they put this into the player table, as we could use a global db variable to hold first player as easily.
But I am just following the existing code more-or-less. It is not recommended to modify player table in general.

=== Game State Variables ===
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>
parent::__construct();
$this->initGameStateLabels(
[
"currentHandType" => 10,
"trickColor" => 11,
"alreadyPlayedHearts" => 12,
]
);;

$this->cards = $this->deckFactory->createDeck('card');
</pre>

If you see errors in IDE its because we also have to declared "cards" as class member, add ''protected $cards;'' before the contructor.

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:

*"trickColor": numbers from 1 to 4 that map to card suit (not sure why it's called color; maybe it's a translation from French);
*"alreadyPlayedHearts": a boolean flag (0 or 1) indicating whether somebody used hearts on the trick;
*"currentHandType": stores the value to indicate who to give cards to during exchange.

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>

Since we changed the db, 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>

Code Rev [https://github.com/elaskavaia/bga-heartsla/tree/acd1926a6c09dc9afd0752cb6b78eef17c5dfe5c]

=== 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 "TODO: Setup the initial game situation here" comment.
<pre>
// Init global values with their initial values

// Note: hand types: 0 = give 3 cards to player on the left
// 1 = give 3 cards to player on the right
// 2 = give 3 cards to player opposite
// 3 = keep cards
$this->setGameStateInitialValue('currentHandType', 0);

// Set current trick color to zero (= no trick color)
$this->setGameStateInitialValue('trickColor', 0);

// Mark if we already played hearts during this hand
$this->setGameStateInitialValue('alreadyPlayedHearts', 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.
<pre>
// Create cards
$cards = [];
foreach (self::$CARD_SUITS as $suit => $suit_info) {
// spade, heart, diamond, club
foreach (self::$CARD_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 ''self:$CARD_SUITS''.
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 (if you already have ''self::$CARD_TYPES'', replace it)

<pre>
elf::$CARD_SUITS = [
1 => [
'name' => clienttranslate('Spade'),
],
2 => [
'name' => clienttranslate('Heart'),
],
3 => [
'name' => clienttranslate('Club'),
],
4 => [
'name' => clienttranslate('Diamond'),
]
];

self::$CARD_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 declared these fields in the class
private static array $CARD_SUITS;
private static array $CARD_TYPES;

==== 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) {
$cards = $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', $current_player_id);

// 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 .js file in the setup function (which is the receiver of getAllDatas) replace our hack of putting 5 of Hearts directly into the hand with:

<pre>
// Cards in player's hand
for (var i in this.gamedatas.hand) {
var card = this.gamedatas.hand[i];
var color = card.type;
var value = card.type_arg;
this.playerHand.addToStockWithId(this.getCardUniqueId(color, value), card.id);
}
</pre>

At this point, you could start a new game and each player should see their hand!

=== Cards on Table ===
To the setup method, add:
// Cards played on table
for (i in this.gamedatas.cardsontable) {
var card = this.gamedatas.cardsontable[i];
var color = card.type;
var value = card.type_arg;
var player_id = card.location_arg;
this.playCardOnTable(player_id, color, value, card.id);
}
Add the '''playCardOnTable''' function in the "utilities" section.

<pre>
playCardOnTable : function(player_id, color, value, card_id) {
// player_id => direction
this.addTableCard(value, color, player_id, player_id);

if (player_id != this.player_id) {
// Some opponent played a card
// Move card from player panel
this.placeOnObject('cardontable_' + player_id, 'overall_player_board_' + player_id);
} else {
// You played a card. If it exists in your hand, move card from there and remove
// corresponding item

if ($('myhand_item_' + card_id)) {
this.placeOnObject('cardontable_' + player_id, 'myhand_item_' + card_id);
this.playerHand.removeFromStockById(card_id);
}
}

// In any case: move it to its final destination
this.slideToObject('cardontable_' + player_id, 'playertablecard_' + player_id).play();
},
</pre>

For this to work we also need to define the addTableCard
<pre>
addTableCard(value, color, card_player_id, playerTableId) {
const x = value - 2;
const y = color - 1;
document.getElementById('playertablecard_' + playerTableId).insertAdjacentHTML('beforeend', `
<div class="card cardontable" id="cardontable_${card_player_id}" style="background-position:-${x}00% -${y}00%"></div>
`);
},
</pre>

What this does is basically create another card object, because if it is not our card it's not in our hand (Stock) so
we have to create it out of thin air. Now we have an object with an id of 'cardontable_' + player_id. Depending
on who is playing it we either place it on the player miniboard or in hand (and remove it from hand stock). Then we animate the card move.

We also should fix our .css file now to add style for cardontable and REMOVE background for playertablecard which really is a placeholder div and not a card. (Don't miss the remove step; it will be all screwy if you do!)

<pre>
.playertablecard {
display: inline-block;
position: relative;
margin-top: 5px;
width: 72px;
height: 96px;
/* we remove background-image here */
}

/*** cards on table ***/

.cardontable {
position: absolute;
width: 72px;
height: 96px;
background-image: url('img/cards.jpg');
}
</pre>

Next, we will hook-up clicking on card and test if our ''playCardOnTable'' works.

Find ''onPlayerHandSelectionChanged'' function in the JS file, we should have logging there like ''console.log("on playCard "+card_id);''
So after that insert this (Note: this code is for testing we will replace it with server interaction after we test it.):
<pre>
console.log("on playCard " + card_id);
// type is (color - 1) * 13 + (value - 2)
var type = items[0].type;
var color = Math.floor(type / 13) + 1;
var value = (type % 13) + 2;

this.playCardOnTable(this.player_id, color, value, card_id);
</pre>
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]]

Code Rev [https://github.com/elaskavaia/bga-heartsla/tree/0ed80e254a6d0c29f267b308d1c2016db90fd4f6]

==State Machine==

Now we need to create a game state machine. So the states are (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 is selected who will start a new trick ("newTrick")
*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) ("nextHand")

The state handling spread across multiple files, so you have to make sure all pieces are connected together.
The state machine states.php defines all the states, and function handlers on php side in a form of string,
and if any of these functions are not implemented it would be very hard to debug because it will break in random places.

So .states.php (remove all template states and replace with these)

<pre>
$machinestates = array(
/// New hand
2 => array(
"name" => "newHand",
"description" => "",
"type" => "game",
"action" => "stNewHand",
"updateGameProgression" => true,
"transitions" => array( "" => 30 )
),

21 => array(
"name" => "giveCards",
"description" => clienttranslate('Some players must choose 3 cards to give to ${direction}'),
"descriptionmyturn" => clienttranslate('${you} must choose 3 cards to give to ${direction}'),
"type" => "multipleactiveplayer",
"action" => "stGiveCards",
"args" => "argGiveCards",
"possibleactions" => array( "actGiveCards" ),
"transitions" => array( "giveCards" => 22, "skip" => 22 )
),

22 => array(
"name" => "takeCards",
"description" => "",
"type" => "game",
"action" => "stTakeCards",
"transitions" => array( "startHand" => 30, "skip" => 30 )
),

// Trick

30 => array(
"name" => "newTrick",
"description" => "",
"type" => "game",
"action" => "stNewTrick",
"transitions" => array( "" => 31 )
),
31 => array(
"name" => "playerTurn",
"description" => clienttranslate('${actplayer} must play a card'),
"descriptionmyturn" => clienttranslate('${you} must play a card'),
"type" => "activeplayer",
"possibleactions" => array( "actPlayCard" ),
"transitions" => array( "playCard" => 32 )
),
32 => array(
"name" => "nextPlayer",
"description" => "",
"type" => "game",
"action" => "stNextPlayer",
"transitions" => array( "nextPlayer" => 31, "nextTrick" => 30, "endHand" => 40 )
),

// End of the hand (scoring, etc...)
40 => array(
"name" => "endHand",
"description" => "",
"type" => "game",
"action" => "stEndHand",
"transitions" => array( "nextHand" => 2, "endGame" => 99 )
),

);
</pre>

The full details on these fields are in [[Your_game_state_machine:_states.inc.php]].

But basically we have Player states, in which a human player has to perform an "action" by pressing some button in the UI or selecting some game item, which will trigger js handler, which will do an ajax call to the server.

To make it run we have to define all the handler functions that we referenced in states, which are - one function for state arguments argGiveCards, 4 functions for robot states (where the game performs some action)
and 1 function for player actions handling.
In Game.php, find 'Game state arguments' section and paste this in:
<pre>
function argGiveCards() {
return [];
}
</pre>

This normally passes some parameters to states, but we don't need anything yet. It's good to have a placeholder there anyway, so we can fix it later.
Important: even when it's a stub, this function must return an array not a scalar.

Let's do stubs for other functions, find the game state actions section in Game.php file and insert these (replace all st* method defined in template)
<pre>
function stNewHand() {
// Take back all cards (from any location => null) to deck
$this->cards->moveAllCardsInLocation(null, "deck");
$this->cards->shuffle('deck');
// Deal 13 cards to each players
// Create deck, shuffle it and give 13 initial cards
$players = $this->loadPlayersBasicInfos();
foreach ( $players as $player_id => $player ) {
$cards = $this->cards->pickCards(13, 'deck', $player_id);
// Notify player about his cards
$this->notify->player($player_id, 'newHand', '', array ('cards' => $cards ));
}
$this->setGameStateValue('alreadyPlayedHearts', 0);
$this->gamestate->nextState("");
}

function stNewTrick() {
// New trick: active the player who wins the last trick, or the player who own the club-2 card
// Reset trick color to 0 (= no color)
$this->setGameStateInitialValue('trickColor', 0);
$this->gamestate->nextState();
}

function stNextPlayer() {
// Active next player OR end the trick and go to the next trick OR end the hand
if ($this->cards->countCardInLocation('cardsontable') == 4) {
// This is the end of the trick
// Move all cards to "cardswon" of the given player
$best_value_player_id = $this->activeNextPlayer(); // TODO figure out winner of trick
$this->cards->moveAllCardsInLocation('cardsontable', 'cardswon', null, $best_value_player_id);

if ($this->cards->countCardInLocation('hand') == 0) {
// End of the hand
$this->gamestate->nextState("endHand");
} else {
// End of the trick
$this->gamestate->nextState("nextTrick");
}
} else {
// Standard case (not the end of the trick)
// => just active the next player
$player_id = $this->activeNextPlayer();
$this->giveExtraTime($player_id);
$this->gamestate->nextState('nextPlayer');
}
}

function stEndHand() {
$this->gamestate->nextState("nextHand");
}

</pre>
Important: All state actions game or player must end with state transition (or thrown exception). Also make sure it's ONLY one state transition,
if you accidentally fall through after state transition and do another one it will be a real mess and head scratching for long time.

Now find 'player actions' section and paste this code there (replace all existing act* functions)
<pre>
function actPlayCard(int $card_id) {
$player_id = $this->getActivePlayerId();
throw new \BgaUserException(clienttranslate('Not implemented: ${player_id} plays ${card_id}'), [
"player_id" => "$player_id",
"card_id" => $card_id,
]);

}
</pre>
We won't implement it yet but throw an exception which we will see if interaction is working properly

If your game is running you have to exit it. When we change state machine in the middle of the game usually it won't be good.

Now the game should start but it would not be any different than before because we have to implement actual interactions.
It's good to check if it's still working though (and if it was running before you have to exit because we changed state machine and normally it will break stuff).

NOTE: When you play a card, you will not yet get the "Not implemented" message. That is added in the next section.

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
<pre>
onUpdateActionButtons: function (stateName, args) {
console.log("onUpdateActionButtons: " + stateName, args);

if (this.isCurrentPlayerActive()) {
switch (stateName) {
case "playerTurn":
break;
}
}
},
</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.

Eventhough we can it ajax call the API now called "bgaPerformAction" and this is what you should be using.

So in .js code replace onPlayerHandSelectionChanged with
<pre>
onPlayerHandSelectionChanged : function() {
var items = this.playerHand.getSelectedItems();

if (items.length > 0) {
var action = 'actPlayCard';
if (this.checkAction(action, true)) {
// Can play a card
var card_id = items[0].id;
this.bgaPerformAction(action, {
card_id : card_id,
});

this.playerHand.unselectAll();
} else if (this.checkAction('actGiveCards')) {
// Can give cards => let the player select some cards
} else {
this.playerHand.unselectAll();
}
}
},
</pre>

Now when you click on card you should get a server response: Not implemented...

Lets implement it, in Game.php
<pre>

function actPlayCard(int $card_id) {
$player_id = $this->getActivePlayerId();
$this->cards->moveCard($card_id, 'cardsontable', $player_id);
// XXX check rules here
$currentCard = $this->cards->getCard($card_id);
// And notify
$this->notify->all('playCard', clienttranslate('${player_name} plays ${value_displayed} ${color_displayed}'), array (
'i18n' => array ('color_displayed','value_displayed' ),'card_id' => $card_id,'player_id' => $player_id,
'player_name' => $this->getActivePlayerName(),
'value' => $currentCard ['type_arg'],
'value_displayed' => self::$CARD_TYPES [$currentCard ['type_arg']] ['name'],
'color' => $currentCard ['type'],
'color_displayed' => self::$CARD_SUITS [$currentCard ['type']] ['name'] ));
// Next player
$this->gamestate->nextState('playCard');
}

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

<pre>
setupNotifications : function() {
console.log('notifications subscriptions setup');
// table of notif type to delay in milliseconds
const notifs = [
['newHand', 1],
['playCard', 100],
];

notifs.forEach((notif) => {
dojo.subscribe(notif[0], this, `notif_${notif[0]}`);
this.notifqueue.setSynchronous(notif[0], notif[1]);
});

},

notif_newHand : function(notif) {
// We received a new full hand of 13 cards.
this.playerHand.removeAll();

for ( var i in notif.args.cards) {
var card = notif.args.cards[i];
var color = card.type;
var value = card.type_arg;
this.playerHand.addToStockWithId(this.getCardUniqueId(color, value), card.id);
}
},

notif_playCard : function(notif) {
// Play a card on the table
this.playCardOnTable(notif.args.player_id, notif.args.color, notif.args.value, notif.args.card_id);
},
</pre>

Now it actually works through the server when you click on card - the move is recorded. If you test it now 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 we need to send notification about it
and have a handler for it

So in Game.php file add notification in stNextPlayer function after moveAllCardsInLocation call:

<pre>
// Notify
// 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 = $this->loadPlayersBasicInfos();
$this->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']
) );
$this->notify->all( 'giveAllCardsToPlayer','', array(
'player_id' => $best_value_player_id
) );
</pre>

And in .js file add 2 more notification handlers.

This is to subscribe in setupNotifications function
<pre>
const notifs = [
...
['trickWin', 1000],
['giveAllCardsToPlayer', 600],
];
</pre>

And these are handlers
<pre>
notif_trickWin : function(notif) {
// We do nothing here (just wait in order players can view the 4 cards played before they're gone.
},
notif_giveAllCardsToPlayer : function(notif) {
// Move all cards on table to given table, then destroy them
var winner_id = notif.args.player_id;
for ( var player_id in this.gamedatas.players) {
var anim = this.slideToObject('cardontable_' + player_id, 'overall_player_board_' + winner_id);
dojo.connect(anim, 'onEnd', function(node) {
dojo.destroy(node);
});
anim.play();
}
},
</pre>

So 'trickWin' notification does not do much except it will delay the processing of next notification by 1 second (1000 ms)
and it will log the message (that happens independently of what handler does).
<i>Note: if on the other hand you don't want to log but want to do something else, send an empty message</i>

Now after the trick you see all cards move towards the "player's stash".

==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 'trickColor' which we already conveniently created.

In Game.php file find the actPlayCard function and add this before notify functions
$currentTrickColor = $this->getGameStateValue( 'trickColor' ) ;
if( $currentTrickColor == 0 )
$this->setGameStateValue( 'trickColor', $currentCard['type'] );

This will make sure we remember the first suit being played, now to use it modify the stNextPlayer function to fix our TODO comment
<pre>
function stNextPlayer() {
// Active next player OR end the trick and go to the next trick OR end the hand
if ($this->cards->countCardInLocation('cardsontable') == 4) {
// This is the end of the trick
$cards_on_table = $this->cards->getCardsInLocation('cardsontable');
$best_value = 0;
$best_value_player_id = null;
$currentTrickColor = $this->getGameStateValue('trickColor');
foreach ( $cards_on_table as $card ) {
// Note: type = card color
if ($card ['type'] == $currentTrickColor) {
if ($best_value_player_id === null || $card ['type_arg'] > $best_value) {
$best_value_player_id = $card ['location_arg']; // Note: location_arg = player who played this card on table
$best_value = $card ['type_arg']; // Note: type_arg = value of the card
}
}
}

// Active this player => he's the one who starts the next trick
$this->gamestate->changeActivePlayer( $best_value_player_id );

// Move all cards to "cardswon" of the given player
$this->cards->moveAllCardsInLocation('cardsontable', 'cardswon', null, $best_value_player_id);

// Notify
// ... same code here 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, also
we want to show that in the log.
In addition scoring can be shown in [[Game_interface_logic:_yourgamename.js#Scoring_dialogs|Scoring Dialog]] using tableWindow notification, but it is a tutorial on its own and you can do it as homework (it is part of original heart game).

so in Game.php our stEndHand function will look like

<pre>
function stEndHand() {
// Count and score points, then end the game or go to the next hand.
$players = $this->loadPlayersBasicInfos();
// Gets all "hearts" + queen of spades

$player_to_points = array ();
foreach ( $players as $player_id => $player ) {
$player_to_points [$player_id] = 0;
}
$cards = $this->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) {
$this->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 ($this->playerScore->getMin() <= -100) {
// Trigger the end of the game !
$this->gamestate->nextState("endGame");
return;
}

$this->gamestate->nextState("nextHand");
}
</pre>

So it should more less work now, including end of game condition. Try to play it!

==Additional stuff==

The following things were not implemented and can add them yourself by looking at the code of original hearts game:

*Remove debug code from setupNewGame to deal cards, cards are now dealt in stNewHand state handler
*Rule checking and rule enforcements in actPlayCard function
*Start scoring with 100 points each and end when <= 0
*Fix scoring rules with Q of spades and 26 point reverse scoring
*First player one with 2 club
*Add progress handling
*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

2025-10-05T04:47:53Z

ShaharHarshuv: /* Game Setup */

{{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]]).
* Know the rules for Hearts
* 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]

== 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. 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.
</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 full game can be found in your FTP home folder, after getting read-only access: https://en.doc.boardgamearena.com/First_steps_with_BGA_Studio#Set_up_dev_environment_ide,_editor_and_File_Sync

== 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://github.com/elaskavaia/bga-heartsla/blob/4b3a73eeb5acae961ade18473af119e8ce8d1a8f/img/cards.jpg hearts img/cards.jpg] into img/ folder of your project.
<blockquote>There are better quality deck of cards image at https://en.doc.boardgamearena.com/Common_board_game_elements_image_resources</blockquote>

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>
document.getElementById('game_play_area').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 (the image slightly obsolete, you may see more stuff there and different prompt).

[[File:Heartsla-tpl2.png]]

Now lets add a card into the hand, just so you can feel it. Edit the html string we inserted earlier and a playertablecard div inside a hand div
<pre>
...
<div id="myhand">
<div class="playertablecard"></div>
</div>
...
</pre>

Edit .css file
<pre>
.playertablecard {
display: inline-block;
position: relative;
margin-top: 5px;
width: 72px;
height: 96px;
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:

[[File:Heartsla-tpl3.png]]

Awesome! Now lets do the rest of layout.

Note: If you don't see the card a) check it was synced to remote folder b) force reload page

Let's complete the template string we created for the hand. You template should have this code, just leave it there
<pre>

// Example to add a div on the game area
document.getElementById("game_play_area").insertAdjacentHTML("beforeend",
`
<div id="player-tables"></div>
`
);
</pre>

Then change the following template code to this
<pre>
// Setting up player boards
var numPlayers = Object.keys(gamedatas.players).length;
Object.values(gamedatas.players).forEach((player, index) => {
document.getElementById("player-tables").insertAdjacentHTML(
"beforeend",
`
<div class="playertable whiteblock playertable_${DIRECTIONS[numPlayers][index]}">
<div class="playertablename" style="color:#${player.color};"><span class="dealer_token" id="dealer_token_p${player.id}">🃏 </span>${player.name}</div>
<div class="playertablecard" id="playertablecard_${player.id}"></div>
<div class="playertablename" id="hand_score_wrap_${player.id}"><span class="hand_score_label"></span> <span id="hand_score_${player.id}"></span></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
heartslav.js:68 Uncaught (in promise) ReferenceError: DIRECTIONS is not defined

For this new code to work, we need to add a constant at the beginning of the JS file, defining the expected position of each player (right after copyright comment):
<pre>
const DIRECTIONS = {
3: ['S', 'W', 'E'],
4: ['S', 'W', 'N', 'E'],
};
</pre>

Reload. If everything went well you should see this:

[[File:Hearts all rows.png|alt=Display a list of all players, with a dummy card in each position]]

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>
/** Table layout **/

#player-tables {
position: relative;
width: 710px;
height: 340px;
}

.playertablename {
font-weight: bold;
}

.playertable {
position: absolute;
text-align: center;
width: 180px;
height: 130px;
}

.playertable_N {
left: 50%;
top: 0px;
margin-left: -90px; /* half of 180 */
}
.playertable_S {
left: 50%;
bottom: 0px;
margin-left: -90px; /* half of 180 */
}
.playertable_W {
left: 0px;
top: 50%;
margin-top: -55px; /* half of 130 */
}
.playertable_E {
right: 0px;
top: 50%;
margin-top: -55px; /* half of 130 */
}
</pre>

Now you force Reload and you should see this:
[[File:Heartsla-tpl5.png]]

This is almost all we need for graphics and layout, there are few tweaks left there but lets do some more heavy lifting now.

<i>Note: if you did not see changes you may have not force reloaded, force means you use Ctrl+F5 or Cltr+Shift-R, if you don't "force" browser will use cached version of images! Which is not what you just changed</i>

<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 JS Stock ==

The BGA framework provides a few out of the box classes to deal with cards. The client side
contains a class called [[Stock]] and it can be used for any dynamic html "pieces" management that uses
common sprite images. 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 13x4 grid of images stitched together,
which is a very efficient way to transport images. So we will use the Stock class to mark up these images and create
"card" divs for us.

First, we need to add '''ebg/stock''' as a dependency in the .js file:
<pre>
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/stock" /// <==== HERE, don't forget comma before
],
</pre>

Then add this to the Javascript constructor, this will define size of our cards
<pre>
console.log('hearts constructor');
this.cardwidth = 72;
this.cardheight = 96;
</pre>

The stock is initialized in the Javascript "setup" method, after we have created the "myhand" element", like this:
<pre>
// TODO: Set up your game interface here, according to "gamedatas"

// Player hand
this.playerHand = new ebg.stock(); // new stock object for hand
this.playerHand.create( this, $('myhand'), this.cardwidth, this.cardheight );
</pre>

As parameters of the "create" method, we provided the width/height of an item (a card), and the container div "myhand" - which is an id of "div" element we have created before.

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

Here's how we tell stock what item types to display (add after .create):
<pre>
this.playerHand.image_items_per_row = 13; // 13 images per row

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

And add this function to the utilities section
<pre>
// Get card unique identifier based on its color and value
getCardUniqueId : function(color, value) {
return (color - 1) * 13 + (value - 2);
},
</pre>

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

Note: we need to generate a unique ID for each type of card based on its color and value. For that we create a function '''getCardUniqueId'''. The type is the unique identifier of the TYPE of the card, e.g., the queen of spades encoded as an integer. If our deck had 2 standard card decks we would have had 2 queens of spades; they would share the same type and the same image but would have different ids. NOTE: It's unfortunate that they named this '''getCardUniqueId'''; it should have been '''getCardUniqueType''', because it really isn't an id, but a TYPE of card. The type of the item should either be a reversible function of its properties (i.e., kind of suite * 13 + value) or just an enumerator described in material.inc.php. In this specific case it's a synthetic type id, which also the same as the number of the card in the sprite image (i.e., if you enumerate each image in sprite going left to right, then top to bottom).

Now let's add the 5 of Hearts to the player's hand just for fun (this code will go in setup method after types initialization):

<pre>
// 2 = hearts, 5 is 5, and 42 is the card id, which normally would come from db
this.playerHand.addToStockWithId( this.getCardUniqueId( 2, 5 ), 42 );
</pre>

This will add the card with id 42 and type 16 ( (2-1)*13+(5-2)=16 ).

Note that number 16 would not be something you can see in database, Deck database will have separate field for type and type_arg where type is suite and type_arg is number, so its not the same thing, but you can use same formula to convert. Number 42 on the other hand would be id field in database. But we get to database in the later section.

If you reload now you should see the 5 of hearts in "your hand".

You may see some weird graphics glitches - its because we did not remove our hack with background from .css yet. You can go to .css file now and remove line with comment "temp hack to see it".

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, after this.playerHand is initialised:

dojo.connect( this.playerHand, 'onChangeSelection', this, 'onPlayerHandSelectionChanged' );

Then find the Player's action comment section in .js file and add a handler after the comment:

<pre>
///////////////////////////////////////////////////
//// Player's action

onPlayerHandSelectionChanged: function () {
var items = this.playerHand.getSelectedItems();

if (items.length > 0) {
if (this.checkAction("actPlayCard", true)) {
// Can play a card

var card_id = items[0].id;
console.log("on playCard " + card_id);

this.playerHand.unselectAll();
} else if (this.checkAction("actGiveCards")) {
// Can give cards => let the player select some cards
} else {
this.playerHand.unselectAll();
}
}
},
</pre>

''Note : If you already have an example handler <code>onCardClick: function( card_id )</code>, go ahead and remove that handler, it is a duplicate of what we are implementing in this tutorial and may cause issues later on.''

The function name of the handler is 4th parameter of the dojo.connect function. Make sure you spell it correctly or there will be unpredictable effects.

Now if you reload, open the Javascript Console (F12), and then click on the card in My Hand, you should see:
on playCard 42
printed on the console

''Note : You need to be the active player to have rights to play a card and so log your message in the console''

== 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 ====
To modify the schema, first exit your existing game(s). Open '''dbmodel.sql''' file and uncomment the card table creation.

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

This is the "card" table which will be managed by the Deck php class.

In addition we want a little piece of information in the players table:

-- add info about first player
ALTER TABLE `player` ADD `player_first` BOOLEAN NOT NULL DEFAULT '0';

Not sure why they put this into the player table, as we could use a global db variable to hold first player as easily.
But I am just following the existing code more-or-less. It is not recommended to modify player table in general.

=== Game State Variables ===
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>
parent::__construct();
$this->initGameStateLabels(
[
"currentHandType" => 10,
"trickColor" => 11,
"alreadyPlayedHearts" => 12,
]
);;

$this->cards = $this->deckFactory->createDeck('card');
</pre>

If you see errors in IDE its because we also have to declared "cards" as class member, add ''protected $cards;'' before the contructor.

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:

*"trickColor": numbers from 1 to 4 that map to card suit (not sure why it's called color; maybe it's a translation from French);
*"alreadyPlayedHearts": a boolean flag (0 or 1) indicating whether somebody used hearts on the trick;
*"currentHandType": stores the value to indicate who to give cards to during exchange.

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>

Since we changed the db, 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>

Code Rev [https://github.com/elaskavaia/bga-heartsla/tree/acd1926a6c09dc9afd0752cb6b78eef17c5dfe5c]

=== 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 "TODO: Setup the initial game situation here" comment.
<pre>
// Init global values with their initial values

// Note: hand types: 0 = give 3 cards to player on the left
// 1 = give 3 cards to player on the right
// 2 = give 3 cards to player opposite
// 3 = keep cards
$this->setGameStateInitialValue('currentHandType', 0);

// Set current trick color to zero (= no trick color)
$this->setGameStateInitialValue('trickColor', 0);

// Mark if we already played hearts during this hand
$this->setGameStateInitialValue('alreadyPlayedHearts', 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.
<pre>
// Create cards
$cards = [];
foreach (self::$CARD_SUITS as $suit => $suit_info) {
// spade, heart, diamond, club
foreach (self::$CARD_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 ''self:$CARD_SUITS''.
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 (if you already have ''self::$CARD_TYPES'', replace it)

<pre>
elf::$CARD_SUITS = [
1 => [
'name' => clienttranslate('Spade'),
],
2 => [
'name' => clienttranslate('Heart'),
],
3 => [
'name' => clienttranslate('Club'),
],
4 => [
'name' => clienttranslate('Diamond'),
]
];

self::$CARD_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 declared these fields in the class
private static array $CARD_SUITS;
private static array $CARD_TYPES;

==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. 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', $current_player_id );

// 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 .js file in the setup function (which is the receiver of getAllDatas) replace our hack of putting 5 of Hearts directly into the hand with:

<pre>
// Cards in player's hand
for ( var i in this.gamedatas.hand) {
var card = this.gamedatas.hand[i];
var color = card.type;
var value = card.type_arg;
this.playerHand.addToStockWithId(this.getCardUniqueId(color, value), card.id);
}

// Cards played on table
for (i in this.gamedatas.cardsontable) {
var card = this.gamedatas.cardsontable[i];
var color = card.type;
var value = card.type_arg;
var player_id = card.location_arg;
this.playCardOnTable(player_id, color, value, card.id);
}
</pre>

This should show hand and tableau cards now, except we are missing the '''playCardOnTable''' function. So find the '''getCardUniqueId''' function which
should be in the utilities section and add this after it:

<pre>
playCardOnTable : function(player_id, color, value, card_id) {
// player_id => direction
this.addTableCard(value, color, player_id, player_id);

if (player_id != this.player_id) {
// Some opponent played a card
// Move card from player panel
this.placeOnObject('cardontable_' + player_id, 'overall_player_board_' + player_id);
} else {
// You played a card. If it exists in your hand, move card from there and remove
// corresponding item

if ($('myhand_item_' + card_id)) {
this.placeOnObject('cardontable_' + player_id, 'myhand_item_' + card_id);
this.playerHand.removeFromStockById(card_id);
}
}

// In any case: move it to its final destination
this.slideToObject('cardontable_' + player_id, 'playertablecard_' + player_id).play();
},
</pre>

For this to work we also need to define the addTableCard
<pre>
addTableCard(value, color, card_player_id, playerTableId) {
const x = value - 2;
const y = color - 1;
document.getElementById('playertablecard_' + playerTableId).insertAdjacentHTML('beforeend', `
<div class="card cardontable" id="cardontable_${card_player_id}" style="background-position:-${x}00% -${y}00%"></div>
`);
},
</pre>

What this does is basically create another card object, because if it is not our card it's not in our hand (Stock) so
we have to create it out of thin air. Now we have an object with an id of 'cardontable_' + player_id. Depending
on who is playing it we either place it on the player miniboard or in hand (and remove it from hand stock). Then we animate the card move.

We also should fix our .css file now to add style for cardontable and REMOVE background for playertablecard which really is a placeholder div and not a card. (Don't miss the remove step; it will be all screwy if you do!)

<pre>
.playertablecard {
display: inline-block;
position: relative;
margin-top: 5px;
width: 72px;
height: 96px;
/* we remove background-image here */
}

/*** cards on table ***/

.cardontable {
position: absolute;
width: 72px;
height: 96px;
background-image: url('img/cards.jpg');
}
</pre>

Now to test that it actually works let's deal cards to players during game initialization:

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 ) {
$cards = $this->cards->pickCards(13, 'deck', $player_id);
}
</pre>

Now when you start the game you should see 13 cards in your hand!

We just need to hook-up clicking on card and test if our playCardOnTable works.

Find onPlayerHandSelectionChanged function in the JS file, we should have logging there like console.log("on playCard "+card_id);
So after that insert this (Note: this code is for testing we will replace it with server interaction after we test it.):
<pre>
console.log("on playCard "+card_id);
// type is (color - 1) * 13 + (value - 2)
var type = items[0].type;
var color = Math.floor(type / 13) + 1;
var value = type % 13 + 2;

this.playCardOnTable(this.player_id,color,value,card_id);
</pre>
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]]

Code Rev [https://github.com/elaskavaia/bga-heartsla/tree/0ed80e254a6d0c29f267b308d1c2016db90fd4f6]

==State Machine==

Now we need to create a game state machine. So the states are (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 is selected who will start a new trick ("newTrick")
*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) ("nextHand")

The state handling spread across multiple files, so you have to make sure all pieces are connected together.
The state machine states.php defines all the states, and function handlers on php side in a form of string,
and if any of these functions are not implemented it would be very hard to debug because it will break in random places.

So .states.php (remove all template states and replace with these)

<pre>
$machinestates = array(
/// New hand
2 => array(
"name" => "newHand",
"description" => "",
"type" => "game",
"action" => "stNewHand",
"updateGameProgression" => true,
"transitions" => array( "" => 30 )
),

21 => array(
"name" => "giveCards",
"description" => clienttranslate('Some players must choose 3 cards to give to ${direction}'),
"descriptionmyturn" => clienttranslate('${you} must choose 3 cards to give to ${direction}'),
"type" => "multipleactiveplayer",
"action" => "stGiveCards",
"args" => "argGiveCards",
"possibleactions" => array( "actGiveCards" ),
"transitions" => array( "giveCards" => 22, "skip" => 22 )
),

22 => array(
"name" => "takeCards",
"description" => "",
"type" => "game",
"action" => "stTakeCards",
"transitions" => array( "startHand" => 30, "skip" => 30 )
),

// Trick

30 => array(
"name" => "newTrick",
"description" => "",
"type" => "game",
"action" => "stNewTrick",
"transitions" => array( "" => 31 )
),
31 => array(
"name" => "playerTurn",
"description" => clienttranslate('${actplayer} must play a card'),
"descriptionmyturn" => clienttranslate('${you} must play a card'),
"type" => "activeplayer",
"possibleactions" => array( "actPlayCard" ),
"transitions" => array( "playCard" => 32 )
),
32 => array(
"name" => "nextPlayer",
"description" => "",
"type" => "game",
"action" => "stNextPlayer",
"transitions" => array( "nextPlayer" => 31, "nextTrick" => 30, "endHand" => 40 )
),

// End of the hand (scoring, etc...)
40 => array(
"name" => "endHand",
"description" => "",
"type" => "game",
"action" => "stEndHand",
"transitions" => array( "nextHand" => 2, "endGame" => 99 )
),

);
</pre>

The full details on these fields are in [[Your_game_state_machine:_states.inc.php]].

But basically we have Player states, in which a human player has to perform an "action" by pressing some button in the UI or selecting some game item, which will trigger js handler, which will do an ajax call to the server.

To make it run we have to define all the handler functions that we referenced in states, which are - one function for state arguments argGiveCards, 4 functions for robot states (where the game performs some action)
and 1 function for player actions handling.
In Game.php, find 'Game state arguments' section and paste this in:
<pre>
function argGiveCards() {
return [];
}
</pre>

This normally passes some parameters to states, but we don't need anything yet. It's good to have a placeholder there anyway, so we can fix it later.
Important: even when it's a stub, this function must return an array not a scalar.

Let's do stubs for other functions, find the game state actions section in Game.php file and insert these (replace all st* method defined in template)
<pre>
function stNewHand() {
// Take back all cards (from any location => null) to deck
$this->cards->moveAllCardsInLocation(null, "deck");
$this->cards->shuffle('deck');
// Deal 13 cards to each players
// Create deck, shuffle it and give 13 initial cards
$players = $this->loadPlayersBasicInfos();
foreach ( $players as $player_id => $player ) {
$cards = $this->cards->pickCards(13, 'deck', $player_id);
// Notify player about his cards
$this->notify->player($player_id, 'newHand', '', array ('cards' => $cards ));
}
$this->setGameStateValue('alreadyPlayedHearts', 0);
$this->gamestate->nextState("");
}

function stNewTrick() {
// New trick: active the player who wins the last trick, or the player who own the club-2 card
// Reset trick color to 0 (= no color)
$this->setGameStateInitialValue('trickColor', 0);
$this->gamestate->nextState();
}

function stNextPlayer() {
// Active next player OR end the trick and go to the next trick OR end the hand
if ($this->cards->countCardInLocation('cardsontable') == 4) {
// This is the end of the trick
// Move all cards to "cardswon" of the given player
$best_value_player_id = $this->activeNextPlayer(); // TODO figure out winner of trick
$this->cards->moveAllCardsInLocation('cardsontable', 'cardswon', null, $best_value_player_id);

if ($this->cards->countCardInLocation('hand') == 0) {
// End of the hand
$this->gamestate->nextState("endHand");
} else {
// End of the trick
$this->gamestate->nextState("nextTrick");
}
} else {
// Standard case (not the end of the trick)
// => just active the next player
$player_id = $this->activeNextPlayer();
$this->giveExtraTime($player_id);
$this->gamestate->nextState('nextPlayer');
}
}

function stEndHand() {
$this->gamestate->nextState("nextHand");
}

</pre>
Important: All state actions game or player must end with state transition (or thrown exception). Also make sure it's ONLY one state transition,
if you accidentally fall through after state transition and do another one it will be a real mess and head scratching for long time.

Now find 'player actions' section and paste this code there (replace all existing act* functions)
<pre>
function actPlayCard(int $card_id) {
$player_id = $this->getActivePlayerId();
throw new \BgaUserException(clienttranslate('Not implemented: ${player_id} plays ${card_id}'), [
"player_id" => "$player_id",
"card_id" => $card_id,
]);

}
</pre>
We won't implement it yet but throw an exception which we will see if interaction is working properly

If your game is running you have to exit it. When we change state machine in the middle of the game usually it won't be good.

Now the game should start but it would not be any different than before because we have to implement actual interactions.
It's good to check if it's still working though (and if it was running before you have to exit because we changed state machine and normally it will break stuff).

NOTE: When you play a card, you will not yet get the "Not implemented" message. That is added in the next section.

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
<pre>
onUpdateActionButtons: function (stateName, args) {
console.log("onUpdateActionButtons: " + stateName, args);

if (this.isCurrentPlayerActive()) {
switch (stateName) {
case "playerTurn":
break;
}
}
},
</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.

Eventhough we can it ajax call the API now called "bgaPerformAction" and this is what you should be using.

So in .js code replace onPlayerHandSelectionChanged with
<pre>
onPlayerHandSelectionChanged : function() {
var items = this.playerHand.getSelectedItems();

if (items.length > 0) {
var action = 'actPlayCard';
if (this.checkAction(action, true)) {
// Can play a card
var card_id = items[0].id;
this.bgaPerformAction(action, {
card_id : card_id,
});

this.playerHand.unselectAll();
} else if (this.checkAction('actGiveCards')) {
// Can give cards => let the player select some cards
} else {
this.playerHand.unselectAll();
}
}
},
</pre>

Now when you click on card you should get a server response: Not implemented...

Lets implement it, in Game.php
<pre>

function actPlayCard(int $card_id) {
$player_id = $this->getActivePlayerId();
$this->cards->moveCard($card_id, 'cardsontable', $player_id);
// XXX check rules here
$currentCard = $this->cards->getCard($card_id);
// And notify
$this->notify->all('playCard', clienttranslate('${player_name} plays ${value_displayed} ${color_displayed}'), array (
'i18n' => array ('color_displayed','value_displayed' ),'card_id' => $card_id,'player_id' => $player_id,
'player_name' => $this->getActivePlayerName(),
'value' => $currentCard ['type_arg'],
'value_displayed' => self::$CARD_TYPES [$currentCard ['type_arg']] ['name'],
'color' => $currentCard ['type'],
'color_displayed' => self::$CARD_SUITS [$currentCard ['type']] ['name'] ));
// Next player
$this->gamestate->nextState('playCard');
}

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

<pre>
setupNotifications : function() {
console.log('notifications subscriptions setup');
// table of notif type to delay in milliseconds
const notifs = [
['newHand', 1],
['playCard', 100],
];

notifs.forEach((notif) => {
dojo.subscribe(notif[0], this, `notif_${notif[0]}`);
this.notifqueue.setSynchronous(notif[0], notif[1]);
});

},

notif_newHand : function(notif) {
// We received a new full hand of 13 cards.
this.playerHand.removeAll();

for ( var i in notif.args.cards) {
var card = notif.args.cards[i];
var color = card.type;
var value = card.type_arg;
this.playerHand.addToStockWithId(this.getCardUniqueId(color, value), card.id);
}
},

notif_playCard : function(notif) {
// Play a card on the table
this.playCardOnTable(notif.args.player_id, notif.args.color, notif.args.value, notif.args.card_id);
},
</pre>

Now it actually works through the server when you click on card - the move is recorded. If you test it now 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 we need to send notification about it
and have a handler for it

So in Game.php file add notification in stNextPlayer function after moveAllCardsInLocation call:

<pre>
// Notify
// 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 = $this->loadPlayersBasicInfos();
$this->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']
) );
$this->notify->all( 'giveAllCardsToPlayer','', array(
'player_id' => $best_value_player_id
) );
</pre>

And in .js file add 2 more notification handlers.

This is to subscribe in setupNotifications function
<pre>
const notifs = [
...
['trickWin', 1000],
['giveAllCardsToPlayer', 600],
];
</pre>

And these are handlers
<pre>
notif_trickWin : function(notif) {
// We do nothing here (just wait in order players can view the 4 cards played before they're gone.
},
notif_giveAllCardsToPlayer : function(notif) {
// Move all cards on table to given table, then destroy them
var winner_id = notif.args.player_id;
for ( var player_id in this.gamedatas.players) {
var anim = this.slideToObject('cardontable_' + player_id, 'overall_player_board_' + winner_id);
dojo.connect(anim, 'onEnd', function(node) {
dojo.destroy(node);
});
anim.play();
}
},
</pre>

So 'trickWin' notification does not do much except it will delay the processing of next notification by 1 second (1000 ms)
and it will log the message (that happens independently of what handler does).
<i>Note: if on the other hand you don't want to log but want to do something else, send an empty message</i>

Now after the trick you see all cards move towards the "player's stash".

==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 'trickColor' which we already conveniently created.

In Game.php file find the actPlayCard function and add this before notify functions
$currentTrickColor = $this->getGameStateValue( 'trickColor' ) ;
if( $currentTrickColor == 0 )
$this->setGameStateValue( 'trickColor', $currentCard['type'] );

This will make sure we remember the first suit being played, now to use it modify the stNextPlayer function to fix our TODO comment
<pre>
function stNextPlayer() {
// Active next player OR end the trick and go to the next trick OR end the hand
if ($this->cards->countCardInLocation('cardsontable') == 4) {
// This is the end of the trick
$cards_on_table = $this->cards->getCardsInLocation('cardsontable');
$best_value = 0;
$best_value_player_id = null;
$currentTrickColor = $this->getGameStateValue('trickColor');
foreach ( $cards_on_table as $card ) {
// Note: type = card color
if ($card ['type'] == $currentTrickColor) {
if ($best_value_player_id === null || $card ['type_arg'] > $best_value) {
$best_value_player_id = $card ['location_arg']; // Note: location_arg = player who played this card on table
$best_value = $card ['type_arg']; // Note: type_arg = value of the card
}
}
}

// Active this player => he's the one who starts the next trick
$this->gamestate->changeActivePlayer( $best_value_player_id );

// Move all cards to "cardswon" of the given player
$this->cards->moveAllCardsInLocation('cardsontable', 'cardswon', null, $best_value_player_id);

// Notify
// ... same code here 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, also
we want to show that in the log.
In addition scoring can be shown in [[Game_interface_logic:_yourgamename.js#Scoring_dialogs|Scoring Dialog]] using tableWindow notification, but it is a tutorial on its own and you can do it as homework (it is part of original heart game).

so in Game.php our stEndHand function will look like

<pre>
function stEndHand() {
// Count and score points, then end the game or go to the next hand.
$players = $this->loadPlayersBasicInfos();
// Gets all "hearts" + queen of spades

$player_to_points = array ();
foreach ( $players as $player_id => $player ) {
$player_to_points [$player_id] = 0;
}
$cards = $this->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) {
$this->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 ($this->playerScore->getMin() <= -100) {
// Trigger the end of the game !
$this->gamestate->nextState("endGame");
return;
}

$this->gamestate->nextState("nextHand");
}
</pre>

So it should more less work now, including end of game condition. Try to play it!

==Additional stuff==

The following things were not implemented and can add them yourself by looking at the code of original hearts game:

*Remove debug code from setupNewGame to deal cards, cards are now dealt in stNewHand state handler
*Rule checking and rule enforcements in actPlayCard function
*Start scoring with 100 points each and end when <= 0
*Fix scoring rules with Q of spades and 26 point reverse scoring
*First player one with 2 club
*Add progress handling
*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

2025-10-05T04:41:48Z

ShaharHarshuv: /* Game Database and Game Initialization */

{{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]]).
* Know the rules for Hearts
* 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]

== 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. 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.
</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 full game can be found in your FTP home folder, after getting read-only access: https://en.doc.boardgamearena.com/First_steps_with_BGA_Studio#Set_up_dev_environment_ide,_editor_and_File_Sync

== 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://github.com/elaskavaia/bga-heartsla/blob/4b3a73eeb5acae961ade18473af119e8ce8d1a8f/img/cards.jpg hearts img/cards.jpg] into img/ folder of your project.
<blockquote>There are better quality deck of cards image at https://en.doc.boardgamearena.com/Common_board_game_elements_image_resources</blockquote>

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>
document.getElementById('game_play_area').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 (the image slightly obsolete, you may see more stuff there and different prompt).

[[File:Heartsla-tpl2.png]]

Now lets add a card into the hand, just so you can feel it. Edit the html string we inserted earlier and a playertablecard div inside a hand div
<pre>
...
<div id="myhand">
<div class="playertablecard"></div>
</div>
...
</pre>

Edit .css file
<pre>
.playertablecard {
display: inline-block;
position: relative;
margin-top: 5px;
width: 72px;
height: 96px;
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:

[[File:Heartsla-tpl3.png]]

Awesome! Now lets do the rest of layout.

Note: If you don't see the card a) check it was synced to remote folder b) force reload page

Let's complete the template string we created for the hand. You template should have this code, just leave it there
<pre>

// Example to add a div on the game area
document.getElementById("game_play_area").insertAdjacentHTML("beforeend",
`
<div id="player-tables"></div>
`
);
</pre>

Then change the following template code to this
<pre>
// Setting up player boards
var numPlayers = Object.keys(gamedatas.players).length;
Object.values(gamedatas.players).forEach((player, index) => {
document.getElementById("player-tables").insertAdjacentHTML(
"beforeend",
`
<div class="playertable whiteblock playertable_${DIRECTIONS[numPlayers][index]}">
<div class="playertablename" style="color:#${player.color};"><span class="dealer_token" id="dealer_token_p${player.id}">🃏 </span>${player.name}</div>
<div class="playertablecard" id="playertablecard_${player.id}"></div>
<div class="playertablename" id="hand_score_wrap_${player.id}"><span class="hand_score_label"></span> <span id="hand_score_${player.id}"></span></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
heartslav.js:68 Uncaught (in promise) ReferenceError: DIRECTIONS is not defined

For this new code to work, we need to add a constant at the beginning of the JS file, defining the expected position of each player (right after copyright comment):
<pre>
const DIRECTIONS = {
3: ['S', 'W', 'E'],
4: ['S', 'W', 'N', 'E'],
};
</pre>

Reload. If everything went well you should see this:

[[File:Hearts all rows.png|alt=Display a list of all players, with a dummy card in each position]]

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>
/** Table layout **/

#player-tables {
position: relative;
width: 710px;
height: 340px;
}

.playertablename {
font-weight: bold;
}

.playertable {
position: absolute;
text-align: center;
width: 180px;
height: 130px;
}

.playertable_N {
left: 50%;
top: 0px;
margin-left: -90px; /* half of 180 */
}
.playertable_S {
left: 50%;
bottom: 0px;
margin-left: -90px; /* half of 180 */
}
.playertable_W {
left: 0px;
top: 50%;
margin-top: -55px; /* half of 130 */
}
.playertable_E {
right: 0px;
top: 50%;
margin-top: -55px; /* half of 130 */
}
</pre>

Now you force Reload and you should see this:
[[File:Heartsla-tpl5.png]]

This is almost all we need for graphics and layout, there are few tweaks left there but lets do some more heavy lifting now.

<i>Note: if you did not see changes you may have not force reloaded, force means you use Ctrl+F5 or Cltr+Shift-R, if you don't "force" browser will use cached version of images! Which is not what you just changed</i>

<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 JS Stock ==

The BGA framework provides a few out of the box classes to deal with cards. The client side
contains a class called [[Stock]] and it can be used for any dynamic html "pieces" management that uses
common sprite images. 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 13x4 grid of images stitched together,
which is a very efficient way to transport images. So we will use the Stock class to mark up these images and create
"card" divs for us.

First, we need to add '''ebg/stock''' as a dependency in the .js file:
<pre>
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/stock" /// <==== HERE, don't forget comma before
],
</pre>

Then add this to the Javascript constructor, this will define size of our cards
<pre>
console.log('hearts constructor');
this.cardwidth = 72;
this.cardheight = 96;
</pre>

The stock is initialized in the Javascript "setup" method, after we have created the "myhand" element", like this:
<pre>
// TODO: Set up your game interface here, according to "gamedatas"

// Player hand
this.playerHand = new ebg.stock(); // new stock object for hand
this.playerHand.create( this, $('myhand'), this.cardwidth, this.cardheight );
</pre>

As parameters of the "create" method, we provided the width/height of an item (a card), and the container div "myhand" - which is an id of "div" element we have created before.

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

Here's how we tell stock what item types to display (add after .create):
<pre>
this.playerHand.image_items_per_row = 13; // 13 images per row

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

And add this function to the utilities section
<pre>
// Get card unique identifier based on its color and value
getCardUniqueId : function(color, value) {
return (color - 1) * 13 + (value - 2);
},
</pre>

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

Note: we need to generate a unique ID for each type of card based on its color and value. For that we create a function '''getCardUniqueId'''. The type is the unique identifier of the TYPE of the card, e.g., the queen of spades encoded as an integer. If our deck had 2 standard card decks we would have had 2 queens of spades; they would share the same type and the same image but would have different ids. NOTE: It's unfortunate that they named this '''getCardUniqueId'''; it should have been '''getCardUniqueType''', because it really isn't an id, but a TYPE of card. The type of the item should either be a reversible function of its properties (i.e., kind of suite * 13 + value) or just an enumerator described in material.inc.php. In this specific case it's a synthetic type id, which also the same as the number of the card in the sprite image (i.e., if you enumerate each image in sprite going left to right, then top to bottom).

Now let's add the 5 of Hearts to the player's hand just for fun (this code will go in setup method after types initialization):

<pre>
// 2 = hearts, 5 is 5, and 42 is the card id, which normally would come from db
this.playerHand.addToStockWithId( this.getCardUniqueId( 2, 5 ), 42 );
</pre>

This will add the card with id 42 and type 16 ( (2-1)*13+(5-2)=16 ).

Note that number 16 would not be something you can see in database, Deck database will have separate field for type and type_arg where type is suite and type_arg is number, so its not the same thing, but you can use same formula to convert. Number 42 on the other hand would be id field in database. But we get to database in the later section.

If you reload now you should see the 5 of hearts in "your hand".

You may see some weird graphics glitches - its because we did not remove our hack with background from .css yet. You can go to .css file now and remove line with comment "temp hack to see it".

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, after this.playerHand is initialised:

dojo.connect( this.playerHand, 'onChangeSelection', this, 'onPlayerHandSelectionChanged' );

Then find the Player's action comment section in .js file and add a handler after the comment:

<pre>
///////////////////////////////////////////////////
//// Player's action

onPlayerHandSelectionChanged: function () {
var items = this.playerHand.getSelectedItems();

if (items.length > 0) {
if (this.checkAction("actPlayCard", true)) {
// Can play a card

var card_id = items[0].id;
console.log("on playCard " + card_id);

this.playerHand.unselectAll();
} else if (this.checkAction("actGiveCards")) {
// Can give cards => let the player select some cards
} else {
this.playerHand.unselectAll();
}
}
},
</pre>

''Note : If you already have an example handler <code>onCardClick: function( card_id )</code>, go ahead and remove that handler, it is a duplicate of what we are implementing in this tutorial and may cause issues later on.''

The function name of the handler is 4th parameter of the dojo.connect function. Make sure you spell it correctly or there will be unpredictable effects.

Now if you reload, open the Javascript Console (F12), and then click on the card in My Hand, you should see:
on playCard 42
printed on the console

''Note : You need to be the active player to have rights to play a card and so log your message in the console''

== 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 ====
To modify the schema, first exit your existing game(s). Open '''dbmodel.sql''' file and uncomment the card table creation.

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

This is the "card" table which will be managed by the Deck php class.

In addition we want a little piece of information in the players table:

-- add info about first player
ALTER TABLE `player` ADD `player_first` BOOLEAN NOT NULL DEFAULT '0';

Not sure why they put this into the player table, as we could use a global db variable to hold first player as easily.
But I am just following the existing code more-or-less. It is not recommended to modify player table in general.

=== Game State Variables ===
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>
parent::__construct();
$this->initGameStateLabels(
[
"currentHandType" => 10,
"trickColor" => 11,
"alreadyPlayedHearts" => 12,
]
);;

$this->cards = $this->deckFactory->createDeck('card');
</pre>

If you see errors in IDE its because we also have to declared "cards" as class member, add ''protected $cards;'' before the contructor.

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:

*"trickColor": numbers from 1 to 4 that map to card suit (not sure why it's called color; maybe it's a translation from French);
*"alreadyPlayedHearts": a boolean flag (0 or 1) indicating whether somebody used hearts on the trick;
*"currentHandType": stores the value to indicate who to give cards to during exchange.

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>

Since we changed the db, 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>

Code Rev [https://github.com/elaskavaia/bga-heartsla/tree/acd1926a6c09dc9afd0752cb6b78eef17c5dfe5c]

=== 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 "Start the game initialization" comment.
<pre>
// Init global values with their initial values

// Note: hand types: 0 = give 3 cards to player on the left
// 1 = give 3 cards to player on the right
// 2 = give 3 cards to player opposite
// 3 = keep cards
$this->setGameStateInitialValue('currentHandType', 0);

// Set current trick color to zero (= no trick color)
$this->setGameStateInitialValue('trickColor', 0);

// Mark if we already played hearts during this hand
$this->setGameStateInitialValue('alreadyPlayedHearts', 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.
<pre>
// Create cards
$cards = [];
foreach (self::$CARD_SUITS as $suit => $suit_info) {
// spade, heart, diamond, club
foreach (self::$CARD_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 $this->colors.
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

<pre>
self::$CARD_SUITS = [
1 => [
'name' => clienttranslate('Spade'),
],
2 => [
'name' => clienttranslate('Heart'),
],
3 => [
'name' => clienttranslate('Club'),
],
4 => [
'name' => clienttranslate('Diamond'),
]
];

self::$CARD_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 declared these fields in the class
private static array $CARD_SUITS;
private static array $CARD_TYPES;

==Full game model synchronisation==

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. 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', $current_player_id );

// 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 .js file in the setup function (which is the receiver of getAllDatas) replace our hack of putting 5 of Hearts directly into the hand with:

<pre>
// Cards in player's hand
for ( var i in this.gamedatas.hand) {
var card = this.gamedatas.hand[i];
var color = card.type;
var value = card.type_arg;
this.playerHand.addToStockWithId(this.getCardUniqueId(color, value), card.id);
}

// Cards played on table
for (i in this.gamedatas.cardsontable) {
var card = this.gamedatas.cardsontable[i];
var color = card.type;
var value = card.type_arg;
var player_id = card.location_arg;
this.playCardOnTable(player_id, color, value, card.id);
}
</pre>

This should show hand and tableau cards now, except we are missing the '''playCardOnTable''' function. So find the '''getCardUniqueId''' function which
should be in the utilities section and add this after it:

<pre>
playCardOnTable : function(player_id, color, value, card_id) {
// player_id => direction
this.addTableCard(value, color, player_id, player_id);

if (player_id != this.player_id) {
// Some opponent played a card
// Move card from player panel
this.placeOnObject('cardontable_' + player_id, 'overall_player_board_' + player_id);
} else {
// You played a card. If it exists in your hand, move card from there and remove
// corresponding item

if ($('myhand_item_' + card_id)) {
this.placeOnObject('cardontable_' + player_id, 'myhand_item_' + card_id);
this.playerHand.removeFromStockById(card_id);
}
}

// In any case: move it to its final destination
this.slideToObject('cardontable_' + player_id, 'playertablecard_' + player_id).play();
},
</pre>

For this to work we also need to define the addTableCard
<pre>
addTableCard(value, color, card_player_id, playerTableId) {
const x = value - 2;
const y = color - 1;
document.getElementById('playertablecard_' + playerTableId).insertAdjacentHTML('beforeend', `
<div class="card cardontable" id="cardontable_${card_player_id}" style="background-position:-${x}00% -${y}00%"></div>
`);
},
</pre>

What this does is basically create another card object, because if it is not our card it's not in our hand (Stock) so
we have to create it out of thin air. Now we have an object with an id of 'cardontable_' + player_id. Depending
on who is playing it we either place it on the player miniboard or in hand (and remove it from hand stock). Then we animate the card move.

We also should fix our .css file now to add style for cardontable and REMOVE background for playertablecard which really is a placeholder div and not a card. (Don't miss the remove step; it will be all screwy if you do!)

<pre>
.playertablecard {
display: inline-block;
position: relative;
margin-top: 5px;
width: 72px;
height: 96px;
/* we remove background-image here */
}

/*** cards on table ***/

.cardontable {
position: absolute;
width: 72px;
height: 96px;
background-image: url('img/cards.jpg');
}
</pre>

Now to test that it actually works let's deal cards to players during game initialization:

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 ) {
$cards = $this->cards->pickCards(13, 'deck', $player_id);
}
</pre>

Now when you start the game you should see 13 cards in your hand!

We just need to hook-up clicking on card and test if our playCardOnTable works.

Find onPlayerHandSelectionChanged function in the JS file, we should have logging there like console.log("on playCard "+card_id);
So after that insert this (Note: this code is for testing we will replace it with server interaction after we test it.):
<pre>
console.log("on playCard "+card_id);
// type is (color - 1) * 13 + (value - 2)
var type = items[0].type;
var color = Math.floor(type / 13) + 1;
var value = type % 13 + 2;

this.playCardOnTable(this.player_id,color,value,card_id);
</pre>
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]]

Code Rev [https://github.com/elaskavaia/bga-heartsla/tree/0ed80e254a6d0c29f267b308d1c2016db90fd4f6]

==State Machine==

Now we need to create a game state machine. So the states are (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 is selected who will start a new trick ("newTrick")
*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) ("nextHand")

The state handling spread across multiple files, so you have to make sure all pieces are connected together.
The state machine states.php defines all the states, and function handlers on php side in a form of string,
and if any of these functions are not implemented it would be very hard to debug because it will break in random places.

So .states.php (remove all template states and replace with these)

<pre>
$machinestates = array(
/// New hand
2 => array(
"name" => "newHand",
"description" => "",
"type" => "game",
"action" => "stNewHand",
"updateGameProgression" => true,
"transitions" => array( "" => 30 )
),

21 => array(
"name" => "giveCards",
"description" => clienttranslate('Some players must choose 3 cards to give to ${direction}'),
"descriptionmyturn" => clienttranslate('${you} must choose 3 cards to give to ${direction}'),
"type" => "multipleactiveplayer",
"action" => "stGiveCards",
"args" => "argGiveCards",
"possibleactions" => array( "actGiveCards" ),
"transitions" => array( "giveCards" => 22, "skip" => 22 )
),

22 => array(
"name" => "takeCards",
"description" => "",
"type" => "game",
"action" => "stTakeCards",
"transitions" => array( "startHand" => 30, "skip" => 30 )
),

// Trick

30 => array(
"name" => "newTrick",
"description" => "",
"type" => "game",
"action" => "stNewTrick",
"transitions" => array( "" => 31 )
),
31 => array(
"name" => "playerTurn",
"description" => clienttranslate('${actplayer} must play a card'),
"descriptionmyturn" => clienttranslate('${you} must play a card'),
"type" => "activeplayer",
"possibleactions" => array( "actPlayCard" ),
"transitions" => array( "playCard" => 32 )
),
32 => array(
"name" => "nextPlayer",
"description" => "",
"type" => "game",
"action" => "stNextPlayer",
"transitions" => array( "nextPlayer" => 31, "nextTrick" => 30, "endHand" => 40 )
),

// End of the hand (scoring, etc...)
40 => array(
"name" => "endHand",
"description" => "",
"type" => "game",
"action" => "stEndHand",
"transitions" => array( "nextHand" => 2, "endGame" => 99 )
),

);
</pre>

The full details on these fields are in [[Your_game_state_machine:_states.inc.php]].

But basically we have Player states, in which a human player has to perform an "action" by pressing some button in the UI or selecting some game item, which will trigger js handler, which will do an ajax call to the server.

To make it run we have to define all the handler functions that we referenced in states, which are - one function for state arguments argGiveCards, 4 functions for robot states (where the game performs some action)
and 1 function for player actions handling.
In Game.php, find 'Game state arguments' section and paste this in:
<pre>
function argGiveCards() {
return [];
}
</pre>

This normally passes some parameters to states, but we don't need anything yet. It's good to have a placeholder there anyway, so we can fix it later.
Important: even when it's a stub, this function must return an array not a scalar.

Let's do stubs for other functions, find the game state actions section in Game.php file and insert these (replace all st* method defined in template)
<pre>
function stNewHand() {
// Take back all cards (from any location => null) to deck
$this->cards->moveAllCardsInLocation(null, "deck");
$this->cards->shuffle('deck');
// Deal 13 cards to each players
// Create deck, shuffle it and give 13 initial cards
$players = $this->loadPlayersBasicInfos();
foreach ( $players as $player_id => $player ) {
$cards = $this->cards->pickCards(13, 'deck', $player_id);
// Notify player about his cards
$this->notify->player($player_id, 'newHand', '', array ('cards' => $cards ));
}
$this->setGameStateValue('alreadyPlayedHearts', 0);
$this->gamestate->nextState("");
}

function stNewTrick() {
// New trick: active the player who wins the last trick, or the player who own the club-2 card
// Reset trick color to 0 (= no color)
$this->setGameStateInitialValue('trickColor', 0);
$this->gamestate->nextState();
}

function stNextPlayer() {
// Active next player OR end the trick and go to the next trick OR end the hand
if ($this->cards->countCardInLocation('cardsontable') == 4) {
// This is the end of the trick
// Move all cards to "cardswon" of the given player
$best_value_player_id = $this->activeNextPlayer(); // TODO figure out winner of trick
$this->cards->moveAllCardsInLocation('cardsontable', 'cardswon', null, $best_value_player_id);

if ($this->cards->countCardInLocation('hand') == 0) {
// End of the hand
$this->gamestate->nextState("endHand");
} else {
// End of the trick
$this->gamestate->nextState("nextTrick");
}
} else {
// Standard case (not the end of the trick)
// => just active the next player
$player_id = $this->activeNextPlayer();
$this->giveExtraTime($player_id);
$this->gamestate->nextState('nextPlayer');
}
}

function stEndHand() {
$this->gamestate->nextState("nextHand");
}

</pre>
Important: All state actions game or player must end with state transition (or thrown exception). Also make sure it's ONLY one state transition,
if you accidentally fall through after state transition and do another one it will be a real mess and head scratching for long time.

Now find 'player actions' section and paste this code there (replace all existing act* functions)
<pre>
function actPlayCard(int $card_id) {
$player_id = $this->getActivePlayerId();
throw new \BgaUserException(clienttranslate('Not implemented: ${player_id} plays ${card_id}'), [
"player_id" => "$player_id",
"card_id" => $card_id,
]);

}
</pre>
We won't implement it yet but throw an exception which we will see if interaction is working properly

If your game is running you have to exit it. When we change state machine in the middle of the game usually it won't be good.

Now the game should start but it would not be any different than before because we have to implement actual interactions.
It's good to check if it's still working though (and if it was running before you have to exit because we changed state machine and normally it will break stuff).

NOTE: When you play a card, you will not yet get the "Not implemented" message. That is added in the next section.

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
<pre>
onUpdateActionButtons: function (stateName, args) {
console.log("onUpdateActionButtons: " + stateName, args);

if (this.isCurrentPlayerActive()) {
switch (stateName) {
case "playerTurn":
break;
}
}
},
</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.

Eventhough we can it ajax call the API now called "bgaPerformAction" and this is what you should be using.

So in .js code replace onPlayerHandSelectionChanged with
<pre>
onPlayerHandSelectionChanged : function() {
var items = this.playerHand.getSelectedItems();

if (items.length > 0) {
var action = 'actPlayCard';
if (this.checkAction(action, true)) {
// Can play a card
var card_id = items[0].id;
this.bgaPerformAction(action, {
card_id : card_id,
});

this.playerHand.unselectAll();
} else if (this.checkAction('actGiveCards')) {
// Can give cards => let the player select some cards
} else {
this.playerHand.unselectAll();
}
}
},
</pre>

Now when you click on card you should get a server response: Not implemented...

Lets implement it, in Game.php
<pre>

function actPlayCard(int $card_id) {
$player_id = $this->getActivePlayerId();
$this->cards->moveCard($card_id, 'cardsontable', $player_id);
// XXX check rules here
$currentCard = $this->cards->getCard($card_id);
// And notify
$this->notify->all('playCard', clienttranslate('${player_name} plays ${value_displayed} ${color_displayed}'), array (
'i18n' => array ('color_displayed','value_displayed' ),'card_id' => $card_id,'player_id' => $player_id,
'player_name' => $this->getActivePlayerName(),
'value' => $currentCard ['type_arg'],
'value_displayed' => self::$CARD_TYPES [$currentCard ['type_arg']] ['name'],
'color' => $currentCard ['type'],
'color_displayed' => self::$CARD_SUITS [$currentCard ['type']] ['name'] ));
// Next player
$this->gamestate->nextState('playCard');
}

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

<pre>
setupNotifications : function() {
console.log('notifications subscriptions setup');
// table of notif type to delay in milliseconds
const notifs = [
['newHand', 1],
['playCard', 100],
];

notifs.forEach((notif) => {
dojo.subscribe(notif[0], this, `notif_${notif[0]}`);
this.notifqueue.setSynchronous(notif[0], notif[1]);
});

},

notif_newHand : function(notif) {
// We received a new full hand of 13 cards.
this.playerHand.removeAll();

for ( var i in notif.args.cards) {
var card = notif.args.cards[i];
var color = card.type;
var value = card.type_arg;
this.playerHand.addToStockWithId(this.getCardUniqueId(color, value), card.id);
}
},

notif_playCard : function(notif) {
// Play a card on the table
this.playCardOnTable(notif.args.player_id, notif.args.color, notif.args.value, notif.args.card_id);
},
</pre>

Now it actually works through the server when you click on card - the move is recorded. If you test it now 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 we need to send notification about it
and have a handler for it

So in Game.php file add notification in stNextPlayer function after moveAllCardsInLocation call:

<pre>
// Notify
// 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 = $this->loadPlayersBasicInfos();
$this->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']
) );
$this->notify->all( 'giveAllCardsToPlayer','', array(
'player_id' => $best_value_player_id
) );
</pre>

And in .js file add 2 more notification handlers.

This is to subscribe in setupNotifications function
<pre>
const notifs = [
...
['trickWin', 1000],
['giveAllCardsToPlayer', 600],
];
</pre>

And these are handlers
<pre>
notif_trickWin : function(notif) {
// We do nothing here (just wait in order players can view the 4 cards played before they're gone.
},
notif_giveAllCardsToPlayer : function(notif) {
// Move all cards on table to given table, then destroy them
var winner_id = notif.args.player_id;
for ( var player_id in this.gamedatas.players) {
var anim = this.slideToObject('cardontable_' + player_id, 'overall_player_board_' + winner_id);
dojo.connect(anim, 'onEnd', function(node) {
dojo.destroy(node);
});
anim.play();
}
},
</pre>

So 'trickWin' notification does not do much except it will delay the processing of next notification by 1 second (1000 ms)
and it will log the message (that happens independently of what handler does).
<i>Note: if on the other hand you don't want to log but want to do something else, send an empty message</i>

Now after the trick you see all cards move towards the "player's stash".

==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 'trickColor' which we already conveniently created.

In Game.php file find the actPlayCard function and add this before notify functions
$currentTrickColor = $this->getGameStateValue( 'trickColor' ) ;
if( $currentTrickColor == 0 )
$this->setGameStateValue( 'trickColor', $currentCard['type'] );

This will make sure we remember the first suit being played, now to use it modify the stNextPlayer function to fix our TODO comment
<pre>
function stNextPlayer() {
// Active next player OR end the trick and go to the next trick OR end the hand
if ($this->cards->countCardInLocation('cardsontable') == 4) {
// This is the end of the trick
$cards_on_table = $this->cards->getCardsInLocation('cardsontable');
$best_value = 0;
$best_value_player_id = null;
$currentTrickColor = $this->getGameStateValue('trickColor');
foreach ( $cards_on_table as $card ) {
// Note: type = card color
if ($card ['type'] == $currentTrickColor) {
if ($best_value_player_id === null || $card ['type_arg'] > $best_value) {
$best_value_player_id = $card ['location_arg']; // Note: location_arg = player who played this card on table
$best_value = $card ['type_arg']; // Note: type_arg = value of the card
}
}
}

// Active this player => he's the one who starts the next trick
$this->gamestate->changeActivePlayer( $best_value_player_id );

// Move all cards to "cardswon" of the given player
$this->cards->moveAllCardsInLocation('cardsontable', 'cardswon', null, $best_value_player_id);

// Notify
// ... same code here 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, also
we want to show that in the log.
In addition scoring can be shown in [[Game_interface_logic:_yourgamename.js#Scoring_dialogs|Scoring Dialog]] using tableWindow notification, but it is a tutorial on its own and you can do it as homework (it is part of original heart game).

so in Game.php our stEndHand function will look like

<pre>
function stEndHand() {
// Count and score points, then end the game or go to the next hand.
$players = $this->loadPlayersBasicInfos();
// Gets all "hearts" + queen of spades

$player_to_points = array ();
foreach ( $players as $player_id => $player ) {
$player_to_points [$player_id] = 0;
}
$cards = $this->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) {
$this->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 ($this->playerScore->getMin() <= -100) {
// Trigger the end of the game !
$this->gamestate->nextState("endGame");
return;
}

$this->gamestate->nextState("nextHand");
}
</pre>

So it should more less work now, including end of game condition. Try to play it!

==Additional stuff==

The following things were not implemented and can add them yourself by looking at the code of original hearts game:

*Remove debug code from setupNewGame to deal cards, cards are now dealt in stNewHand state handler
*Rule checking and rule enforcements in actPlayCard function
*Start scoring with 100 points each and end when <= 0
*Fix scoring rules with Q of spades and 26 point reverse scoring
*First player one with 2 club
*Add progress handling
*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

2025-10-05T04:30:51Z

ShaharHarshuv: /* Game Database and Game Initialization */ fix inconsistency

{{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]]).
* Know the rules for Hearts
* 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]

== 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. 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.
</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 full game can be found in your FTP home folder, after getting read-only access: https://en.doc.boardgamearena.com/First_steps_with_BGA_Studio#Set_up_dev_environment_ide,_editor_and_File_Sync

== 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://github.com/elaskavaia/bga-heartsla/blob/4b3a73eeb5acae961ade18473af119e8ce8d1a8f/img/cards.jpg hearts img/cards.jpg] into img/ folder of your project.
<blockquote>There are better quality deck of cards image at https://en.doc.boardgamearena.com/Common_board_game_elements_image_resources</blockquote>

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>
document.getElementById('game_play_area').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 (the image slightly obsolete, you may see more stuff there and different prompt).

[[File:Heartsla-tpl2.png]]

Now lets add a card into the hand, just so you can feel it. Edit the html string we inserted earlier and a playertablecard div inside a hand div
<pre>
...
<div id="myhand">
<div class="playertablecard"></div>
</div>
...
</pre>

Edit .css file
<pre>
.playertablecard {
display: inline-block;
position: relative;
margin-top: 5px;
width: 72px;
height: 96px;
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:

[[File:Heartsla-tpl3.png]]

Awesome! Now lets do the rest of layout.

Note: If you don't see the card a) check it was synced to remote folder b) force reload page

Let's complete the template string we created for the hand. You template should have this code, just leave it there
<pre>

// Example to add a div on the game area
document.getElementById("game_play_area").insertAdjacentHTML("beforeend",
`
<div id="player-tables"></div>
`
);
</pre>

Then change the following template code to this
<pre>
// Setting up player boards
var numPlayers = Object.keys(gamedatas.players).length;
Object.values(gamedatas.players).forEach((player, index) => {
document.getElementById("player-tables").insertAdjacentHTML(
"beforeend",
`
<div class="playertable whiteblock playertable_${DIRECTIONS[numPlayers][index]}">
<div class="playertablename" style="color:#${player.color};"><span class="dealer_token" id="dealer_token_p${player.id}">🃏 </span>${player.name}</div>
<div class="playertablecard" id="playertablecard_${player.id}"></div>
<div class="playertablename" id="hand_score_wrap_${player.id}"><span class="hand_score_label"></span> <span id="hand_score_${player.id}"></span></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
heartslav.js:68 Uncaught (in promise) ReferenceError: DIRECTIONS is not defined

For this new code to work, we need to add a constant at the beginning of the JS file, defining the expected position of each player (right after copyright comment):
<pre>
const DIRECTIONS = {
3: ['S', 'W', 'E'],
4: ['S', 'W', 'N', 'E'],
};
</pre>

Reload. If everything went well you should see this:

[[File:Hearts all rows.png|alt=Display a list of all players, with a dummy card in each position]]

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>
/** Table layout **/

#player-tables {
position: relative;
width: 710px;
height: 340px;
}

.playertablename {
font-weight: bold;
}

.playertable {
position: absolute;
text-align: center;
width: 180px;
height: 130px;
}

.playertable_N {
left: 50%;
top: 0px;
margin-left: -90px; /* half of 180 */
}
.playertable_S {
left: 50%;
bottom: 0px;
margin-left: -90px; /* half of 180 */
}
.playertable_W {
left: 0px;
top: 50%;
margin-top: -55px; /* half of 130 */
}
.playertable_E {
right: 0px;
top: 50%;
margin-top: -55px; /* half of 130 */
}
</pre>

Now you force Reload and you should see this:
[[File:Heartsla-tpl5.png]]

This is almost all we need for graphics and layout, there are few tweaks left there but lets do some more heavy lifting now.

<i>Note: if you did not see changes you may have not force reloaded, force means you use Ctrl+F5 or Cltr+Shift-R, if you don't "force" browser will use cached version of images! Which is not what you just changed</i>

<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 JS Stock ==

The BGA framework provides a few out of the box classes to deal with cards. The client side
contains a class called [[Stock]] and it can be used for any dynamic html "pieces" management that uses
common sprite images. 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 13x4 grid of images stitched together,
which is a very efficient way to transport images. So we will use the Stock class to mark up these images and create
"card" divs for us.

First, we need to add '''ebg/stock''' as a dependency in the .js file:
<pre>
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/stock" /// <==== HERE, don't forget comma before
],
</pre>

Then add this to the Javascript constructor, this will define size of our cards
<pre>
console.log('hearts constructor');
this.cardwidth = 72;
this.cardheight = 96;
</pre>

The stock is initialized in the Javascript "setup" method, after we have created the "myhand" element", like this:
<pre>
// TODO: Set up your game interface here, according to "gamedatas"

// Player hand
this.playerHand = new ebg.stock(); // new stock object for hand
this.playerHand.create( this, $('myhand'), this.cardwidth, this.cardheight );
</pre>

As parameters of the "create" method, we provided the width/height of an item (a card), and the container div "myhand" - which is an id of "div" element we have created before.

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

Here's how we tell stock what item types to display (add after .create):
<pre>
this.playerHand.image_items_per_row = 13; // 13 images per row

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

And add this function to the utilities section
<pre>
// Get card unique identifier based on its color and value
getCardUniqueId : function(color, value) {
return (color - 1) * 13 + (value - 2);
},
</pre>

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

Note: we need to generate a unique ID for each type of card based on its color and value. For that we create a function '''getCardUniqueId'''. The type is the unique identifier of the TYPE of the card, e.g., the queen of spades encoded as an integer. If our deck had 2 standard card decks we would have had 2 queens of spades; they would share the same type and the same image but would have different ids. NOTE: It's unfortunate that they named this '''getCardUniqueId'''; it should have been '''getCardUniqueType''', because it really isn't an id, but a TYPE of card. The type of the item should either be a reversible function of its properties (i.e., kind of suite * 13 + value) or just an enumerator described in material.inc.php. In this specific case it's a synthetic type id, which also the same as the number of the card in the sprite image (i.e., if you enumerate each image in sprite going left to right, then top to bottom).

Now let's add the 5 of Hearts to the player's hand just for fun (this code will go in setup method after types initialization):

<pre>
// 2 = hearts, 5 is 5, and 42 is the card id, which normally would come from db
this.playerHand.addToStockWithId( this.getCardUniqueId( 2, 5 ), 42 );
</pre>

This will add the card with id 42 and type 16 ( (2-1)*13+(5-2)=16 ).

Note that number 16 would not be something you can see in database, Deck database will have separate field for type and type_arg where type is suite and type_arg is number, so its not the same thing, but you can use same formula to convert. Number 42 on the other hand would be id field in database. But we get to database in the later section.

If you reload now you should see the 5 of hearts in "your hand".

You may see some weird graphics glitches - its because we did not remove our hack with background from .css yet. You can go to .css file now and remove line with comment "temp hack to see it".

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, after this.playerHand is initialised:

dojo.connect( this.playerHand, 'onChangeSelection', this, 'onPlayerHandSelectionChanged' );

Then find the Player's action comment section in .js file and add a handler after the comment:

<pre>
///////////////////////////////////////////////////
//// Player's action

onPlayerHandSelectionChanged: function () {
var items = this.playerHand.getSelectedItems();

if (items.length > 0) {
if (this.checkAction("actPlayCard", true)) {
// Can play a card

var card_id = items[0].id;
console.log("on playCard " + card_id);

this.playerHand.unselectAll();
} else if (this.checkAction("actGiveCards")) {
// Can give cards => let the player select some cards
} else {
this.playerHand.unselectAll();
}
}
},
</pre>

''Note : If you already have an example handler <code>onCardClick: function( card_id )</code>, go ahead and remove that handler, it is a duplicate of what we are implementing in this tutorial and may cause issues later on.''

The function name of the handler is 4th parameter of the dojo.connect function. Make sure you spell it correctly or there will be unpredictable effects.

Now if you reload, open the Javascript Console (F12), and then click on the card in My Hand, you should see:
on playCard 42
printed on the console

''Note : You need to be the active player to have rights to play a card and so log your message in the console''

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

To modify the schema, first exit your existing game(s). Open '''dbmodel.sql''' file and uncomment the card table creation.

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

This is the "card" table which will be managed by the Deck php class.

In addition we want a little piece of information in the players table:

-- add info about first player
ALTER TABLE `player` ADD `player_first` BOOLEAN NOT NULL DEFAULT '0';

Not sure why they put this into the player table, as we could use a global db variable to hold first player as easily.
But I am just following the existing code more-or-less. It is not recommended to modify player table in general.

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>
parent::__construct();
$this->initGameStateLabels(
[
"currentHandType" => 10,
"trickColor" => 11,
"alreadyPlayedHearts" => 12,
]
);;

$this->cards = $this->deckFactory->createDeck('card');
</pre>

If you see errors in IDE its because we also have to declared "cards" as class member, add protected $cards; before the contructor.

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:

* "trickColor": numbers from 1 to 4 that map to card suit (not sure why it's called color; maybe it's a translation from French);
* "alreadyPlayedHearts": a boolean flag (0 or 1) indicating whether somebody used hearts on the trick;
* "currentHandType": stores the value to indicate who to give cards to during exchange.

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: lower in the code there is a line that needs to be removed in order for the game to start. Search for it and remove it now.
$this->setGameStateInitialValue("my_first_global_variable", 0);

Since we changed the db, 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>

Code Rev [https://github.com/elaskavaia/bga-heartsla/tree/acd1926a6c09dc9afd0752cb6b78eef17c5dfe5c]

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 "Start the game initialization" comment.
<pre>
// Init global values with their initial values

// Note: hand types: 0 = give 3 cards to player on the left
// 1 = give 3 cards to player on the right
// 2 = give 3 cards to player opposite
// 3 = keep cards
$this->setGameStateInitialValue( 'currentHandType', 0 );

// Set current trick color to zero (= no trick color)
$this->setGameStateInitialValue( 'trickColor', 0 );

// Mark if we already played hearts during this hand
$this->setGameStateInitialValue( 'alreadyPlayedHearts', 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.
<pre>
// Create cards
$cards = [];
foreach (self::$CARD_SUITS as $suit => $suit_info) {
// spade, heart, diamond, club
foreach (self::$CARD_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 $this->colors.
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

<pre>
self::$CARD_SUITS = [
1 => [
'name' => clienttranslate('Spade'),
],
2 => [
'name' => clienttranslate('Heart'),
],
3 => [
'name' => clienttranslate('Club'),
],
4 => [
'name' => clienttranslate('Diamond'),
]
];

self::$CARD_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 declared these fields in the class
private static array $CARD_SUITS;
private static array $CARD_TYPES;

== Full game model synchronisation ==

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. 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', $current_player_id );

// 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 .js file in the setup function (which is the receiver of getAllDatas) replace our hack of putting 5 of Hearts directly into the hand with:

<pre>
// Cards in player's hand
for ( var i in this.gamedatas.hand) {
var card = this.gamedatas.hand[i];
var color = card.type;
var value = card.type_arg;
this.playerHand.addToStockWithId(this.getCardUniqueId(color, value), card.id);
}

// Cards played on table
for (i in this.gamedatas.cardsontable) {
var card = this.gamedatas.cardsontable[i];
var color = card.type;
var value = card.type_arg;
var player_id = card.location_arg;
this.playCardOnTable(player_id, color, value, card.id);
}
</pre>

This should show hand and tableau cards now, except we are missing the '''playCardOnTable''' function. So find the '''getCardUniqueId''' function which
should be in the utilities section and add this after it:

<pre>
playCardOnTable : function(player_id, color, value, card_id) {
// player_id => direction
this.addTableCard(value, color, player_id, player_id);

if (player_id != this.player_id) {
// Some opponent played a card
// Move card from player panel
this.placeOnObject('cardontable_' + player_id, 'overall_player_board_' + player_id);
} else {
// You played a card. If it exists in your hand, move card from there and remove
// corresponding item

if ($('myhand_item_' + card_id)) {
this.placeOnObject('cardontable_' + player_id, 'myhand_item_' + card_id);
this.playerHand.removeFromStockById(card_id);
}
}

// In any case: move it to its final destination
this.slideToObject('cardontable_' + player_id, 'playertablecard_' + player_id).play();
},
</pre>

For this to work we also need to define the addTableCard
<pre>
addTableCard(value, color, card_player_id, playerTableId) {
const x = value - 2;
const y = color - 1;
document.getElementById('playertablecard_' + playerTableId).insertAdjacentHTML('beforeend', `
<div class="card cardontable" id="cardontable_${card_player_id}" style="background-position:-${x}00% -${y}00%"></div>
`);
},
</pre>

What this does is basically create another card object, because if it is not our card it's not in our hand (Stock) so
we have to create it out of thin air. Now we have an object with an id of 'cardontable_' + player_id. Depending
on who is playing it we either place it on the player miniboard or in hand (and remove it from hand stock). Then we animate the card move.

We also should fix our .css file now to add style for cardontable and REMOVE background for playertablecard which really is a placeholder div and not a card. (Don't miss the remove step; it will be all screwy if you do!)

<pre>
.playertablecard {
display: inline-block;
position: relative;
margin-top: 5px;
width: 72px;
height: 96px;
/* we remove background-image here */
}

/*** cards on table ***/

.cardontable {
position: absolute;
width: 72px;
height: 96px;
background-image: url('img/cards.jpg');
}
</pre>

Now to test that it actually works let's deal cards to players during game initialization:

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 ) {
$cards = $this->cards->pickCards(13, 'deck', $player_id);
}
</pre>

Now when you start the game you should see 13 cards in your hand!

We just need to hook-up clicking on card and test if our playCardOnTable works.

Find onPlayerHandSelectionChanged function in the JS file, we should have logging there like console.log("on playCard "+card_id);
So after that insert this (Note: this code is for testing we will replace it with server interaction after we test it.):
<pre>
console.log("on playCard "+card_id);
// type is (color - 1) * 13 + (value - 2)
var type = items[0].type;
var color = Math.floor(type / 13) + 1;
var value = type % 13 + 2;

this.playCardOnTable(this.player_id,color,value,card_id);
</pre>
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]]

Code Rev [https://github.com/elaskavaia/bga-heartsla/tree/0ed80e254a6d0c29f267b308d1c2016db90fd4f6]

== State Machine ==

Now we need to create a game state machine. So the states are (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 is selected who will start a new trick ("newTrick")
* 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) ("nextHand")

The state handling spread across multiple files, so you have to make sure all pieces are connected together.
The state machine states.php defines all the states, and function handlers on php side in a form of string,
and if any of these functions are not implemented it would be very hard to debug because it will break in random places.

So .states.php (remove all template states and replace with these)

<pre>
$machinestates = array(
/// New hand
2 => array(
"name" => "newHand",
"description" => "",
"type" => "game",
"action" => "stNewHand",
"updateGameProgression" => true,
"transitions" => array( "" => 30 )
),

21 => array(
"name" => "giveCards",
"description" => clienttranslate('Some players must choose 3 cards to give to ${direction}'),
"descriptionmyturn" => clienttranslate('${you} must choose 3 cards to give to ${direction}'),
"type" => "multipleactiveplayer",
"action" => "stGiveCards",
"args" => "argGiveCards",
"possibleactions" => array( "actGiveCards" ),
"transitions" => array( "giveCards" => 22, "skip" => 22 )
),

22 => array(
"name" => "takeCards",
"description" => "",
"type" => "game",
"action" => "stTakeCards",
"transitions" => array( "startHand" => 30, "skip" => 30 )
),

// Trick

30 => array(
"name" => "newTrick",
"description" => "",
"type" => "game",
"action" => "stNewTrick",
"transitions" => array( "" => 31 )
),
31 => array(
"name" => "playerTurn",
"description" => clienttranslate('${actplayer} must play a card'),
"descriptionmyturn" => clienttranslate('${you} must play a card'),
"type" => "activeplayer",
"possibleactions" => array( "actPlayCard" ),
"transitions" => array( "playCard" => 32 )
),
32 => array(
"name" => "nextPlayer",
"description" => "",
"type" => "game",
"action" => "stNextPlayer",
"transitions" => array( "nextPlayer" => 31, "nextTrick" => 30, "endHand" => 40 )
),

// End of the hand (scoring, etc...)
40 => array(
"name" => "endHand",
"description" => "",
"type" => "game",
"action" => "stEndHand",
"transitions" => array( "nextHand" => 2, "endGame" => 99 )
),

);
</pre>

The full details on these fields are in [[Your_game_state_machine:_states.inc.php]].

But basically we have Player states, in which a human player has to perform an "action" by pressing some button in the UI or selecting some game item, which will trigger js handler, which will do an ajax call to the server.

To make it run we have to define all the handler functions that we referenced in states, which are - one function for state arguments argGiveCards, 4 functions for robot states (where the game performs some action)
and 1 function for player actions handling.
In Game.php, find 'Game state arguments' section and paste this in:
<pre>
function argGiveCards() {
return [];
}
</pre>

This normally passes some parameters to states, but we don't need anything yet. It's good to have a placeholder there anyway, so we can fix it later.
Important: even when it's a stub, this function must return an array not a scalar.

Let's do stubs for other functions, find the game state actions section in Game.php file and insert these (replace all st* method defined in template)
<pre>
function stNewHand() {
// Take back all cards (from any location => null) to deck
$this->cards->moveAllCardsInLocation(null, "deck");
$this->cards->shuffle('deck');
// Deal 13 cards to each players
// Create deck, shuffle it and give 13 initial cards
$players = $this->loadPlayersBasicInfos();
foreach ( $players as $player_id => $player ) {
$cards = $this->cards->pickCards(13, 'deck', $player_id);
// Notify player about his cards
$this->notify->player($player_id, 'newHand', '', array ('cards' => $cards ));
}
$this->setGameStateValue('alreadyPlayedHearts', 0);
$this->gamestate->nextState("");
}

function stNewTrick() {
// New trick: active the player who wins the last trick, or the player who own the club-2 card
// Reset trick color to 0 (= no color)
$this->setGameStateInitialValue('trickColor', 0);
$this->gamestate->nextState();
}

function stNextPlayer() {
// Active next player OR end the trick and go to the next trick OR end the hand
if ($this->cards->countCardInLocation('cardsontable') == 4) {
// This is the end of the trick
// Move all cards to "cardswon" of the given player
$best_value_player_id = $this->activeNextPlayer(); // TODO figure out winner of trick
$this->cards->moveAllCardsInLocation('cardsontable', 'cardswon', null, $best_value_player_id);

if ($this->cards->countCardInLocation('hand') == 0) {
// End of the hand
$this->gamestate->nextState("endHand");
} else {
// End of the trick
$this->gamestate->nextState("nextTrick");
}
} else {
// Standard case (not the end of the trick)
// => just active the next player
$player_id = $this->activeNextPlayer();
$this->giveExtraTime($player_id);
$this->gamestate->nextState('nextPlayer');
}
}

function stEndHand() {
$this->gamestate->nextState("nextHand");
}

</pre>
Important: All state actions game or player must end with state transition (or thrown exception). Also make sure it's ONLY one state transition,
if you accidentally fall through after state transition and do another one it will be a real mess and head scratching for long time.

Now find 'player actions' section and paste this code there (replace all existing act* functions)
<pre>
function actPlayCard(int $card_id) {
$player_id = $this->getActivePlayerId();
throw new \BgaUserException(clienttranslate('Not implemented: ${player_id} plays ${card_id}'), [
"player_id" => "$player_id",
"card_id" => $card_id,
]);

}
</pre>
We won't implement it yet but throw an exception which we will see if interaction is working properly

If your game is running you have to exit it. When we change state machine in the middle of the game usually it won't be good.

Now the game should start but it would not be any different than before because we have to implement actual interactions.
It's good to check if it's still working though (and if it was running before you have to exit because we changed state machine and normally it will break stuff).

NOTE: When you play a card, you will not yet get the "Not implemented" message. That is added in the next section.

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
<pre>
onUpdateActionButtons: function (stateName, args) {
console.log("onUpdateActionButtons: " + stateName, args);

if (this.isCurrentPlayerActive()) {
switch (stateName) {
case "playerTurn":
break;
}
}
},
</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.

Eventhough we can it ajax call the API now called "bgaPerformAction" and this is what you should be using.

So in .js code replace onPlayerHandSelectionChanged with
<pre>
onPlayerHandSelectionChanged : function() {
var items = this.playerHand.getSelectedItems();

if (items.length > 0) {
var action = 'actPlayCard';
if (this.checkAction(action, true)) {
// Can play a card
var card_id = items[0].id;
this.bgaPerformAction(action, {
card_id : card_id,
});

this.playerHand.unselectAll();
} else if (this.checkAction('actGiveCards')) {
// Can give cards => let the player select some cards
} else {
this.playerHand.unselectAll();
}
}
},
</pre>

Now when you click on card you should get a server response: Not implemented...

Lets implement it, in Game.php
<pre>

function actPlayCard(int $card_id) {
$player_id = $this->getActivePlayerId();
$this->cards->moveCard($card_id, 'cardsontable', $player_id);
// XXX check rules here
$currentCard = $this->cards->getCard($card_id);
// And notify
$this->notify->all('playCard', clienttranslate('${player_name} plays ${value_displayed} ${color_displayed}'), array (
'i18n' => array ('color_displayed','value_displayed' ),'card_id' => $card_id,'player_id' => $player_id,
'player_name' => $this->getActivePlayerName(),
'value' => $currentCard ['type_arg'],
'value_displayed' => self::$CARD_TYPES [$currentCard ['type_arg']] ['name'],
'color' => $currentCard ['type'],
'color_displayed' => self::$CARD_SUITS [$currentCard ['type']] ['name'] ));
// Next player
$this->gamestate->nextState('playCard');
}

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

<pre>
setupNotifications : function() {
console.log('notifications subscriptions setup');
// table of notif type to delay in milliseconds
const notifs = [
['newHand', 1],
['playCard', 100],
];

notifs.forEach((notif) => {
dojo.subscribe(notif[0], this, `notif_${notif[0]}`);
this.notifqueue.setSynchronous(notif[0], notif[1]);
});

},

notif_newHand : function(notif) {
// We received a new full hand of 13 cards.
this.playerHand.removeAll();

for ( var i in notif.args.cards) {
var card = notif.args.cards[i];
var color = card.type;
var value = card.type_arg;
this.playerHand.addToStockWithId(this.getCardUniqueId(color, value), card.id);
}
},

notif_playCard : function(notif) {
// Play a card on the table
this.playCardOnTable(notif.args.player_id, notif.args.color, notif.args.value, notif.args.card_id);
},
</pre>

Now it actually works through the server when you click on card - the move is recorded. If you test it now 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 we need to send notification about it
and have a handler for it

So in Game.php file add notification in stNextPlayer function after moveAllCardsInLocation call:

<pre>
// Notify
// 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 = $this->loadPlayersBasicInfos();
$this->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']
) );
$this->notify->all( 'giveAllCardsToPlayer','', array(
'player_id' => $best_value_player_id
) );
</pre>

And in .js file add 2 more notification handlers.

This is to subscribe in setupNotifications function
<pre>
const notifs = [
...
['trickWin', 1000],
['giveAllCardsToPlayer', 600],
];
</pre>

And these are handlers
<pre>
notif_trickWin : function(notif) {
// We do nothing here (just wait in order players can view the 4 cards played before they're gone.
},
notif_giveAllCardsToPlayer : function(notif) {
// Move all cards on table to given table, then destroy them
var winner_id = notif.args.player_id;
for ( var player_id in this.gamedatas.players) {
var anim = this.slideToObject('cardontable_' + player_id, 'overall_player_board_' + winner_id);
dojo.connect(anim, 'onEnd', function(node) {
dojo.destroy(node);
});
anim.play();
}
},
</pre>

So 'trickWin' notification does not do much except it will delay the processing of next notification by 1 second (1000 ms)
and it will log the message (that happens independently of what handler does).
<i>Note: if on the other hand you don't want to log but want to do something else, send an empty message</i>

Now after the trick you see all cards move towards the "player's stash".

== 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 'trickColor' which we already conveniently created.

In Game.php file find the actPlayCard function and add this before notify functions
$currentTrickColor = $this->getGameStateValue( 'trickColor' ) ;
if( $currentTrickColor == 0 )
$this->setGameStateValue( 'trickColor', $currentCard['type'] );

This will make sure we remember the first suit being played, now to use it modify the stNextPlayer function to fix our TODO comment
<pre>
function stNextPlayer() {
// Active next player OR end the trick and go to the next trick OR end the hand
if ($this->cards->countCardInLocation('cardsontable') == 4) {
// This is the end of the trick
$cards_on_table = $this->cards->getCardsInLocation('cardsontable');
$best_value = 0;
$best_value_player_id = null;
$currentTrickColor = $this->getGameStateValue('trickColor');
foreach ( $cards_on_table as $card ) {
// Note: type = card color
if ($card ['type'] == $currentTrickColor) {
if ($best_value_player_id === null || $card ['type_arg'] > $best_value) {
$best_value_player_id = $card ['location_arg']; // Note: location_arg = player who played this card on table
$best_value = $card ['type_arg']; // Note: type_arg = value of the card
}
}
}

// Active this player => he's the one who starts the next trick
$this->gamestate->changeActivePlayer( $best_value_player_id );

// Move all cards to "cardswon" of the given player
$this->cards->moveAllCardsInLocation('cardsontable', 'cardswon', null, $best_value_player_id);

// Notify
// ... same code here 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, also
we want to show that in the log.
In addition scoring can be shown in [[Game_interface_logic:_yourgamename.js#Scoring_dialogs|Scoring Dialog]] using tableWindow notification, but it is a tutorial on its own and you can do it as homework (it is part of original heart game).

so in Game.php our stEndHand function will look like

<pre>
function stEndHand() {
// Count and score points, then end the game or go to the next hand.
$players = $this->loadPlayersBasicInfos();
// Gets all "hearts" + queen of spades

$player_to_points = array ();
foreach ( $players as $player_id => $player ) {
$player_to_points [$player_id] = 0;
}
$cards = $this->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) {
$this->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 ($this->playerScore->getMin() <= -100) {
// Trigger the end of the game !
$this->gamestate->nextState("endGame");
return;
}

$this->gamestate->nextState("nextHand");
}
</pre>

So it should more less work now, including end of game condition. Try to play it!

== Additional stuff ==

The following things were not implemented and can add them yourself by looking at the code of original hearts game:

* Remove debug code from setupNewGame to deal cards, cards are now dealt in stNewHand state handler
* Rule checking and rule enforcements in actPlayCard function
* Start scoring with 100 points each and end when <= 0
* Fix scoring rules with Q of spades and 26 point reverse scoring
* First player one with 2 club
* Add progress handling
* 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]]

Setting up BGA Development environment using VSCode

2025-10-05T04:24:03Z

ShaharHarshuv: Add clarification regarding fetching of _ide_helper.php

Microsoft Visual Studio Code is light weight IDE/Editor. All desktops.

== Downloads ==
* Download and install vscode from https://code.visualstudio.com
* Download and install php (8.2) command line interface (for local tests and debugging - optional)

== Extensions ==
Use [https://marketplace.visualstudio.com/items?itemName=NevinFoster.bga-extension-pack&ssr=false#overview BGA Extension Pack] to download all of the recommended extensions with one click.
* PHP Intelephense - https://marketplace.visualstudio.com/items?itemName=bmewburn.vscode-intelephense-client
* Or PHP IntelliSense - https://marketplace.visualstudio.com/items?itemName=zobo.php-intellisense
* PHP Debug - https://marketplace.visualstudio.com/items?itemName=xdebug.php-debug
* SQLTools - https://marketplace.visualstudio.com/items?itemName=mtxr.sqltools
* Prettier - code formatter - https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode
* SFTP (by Natizyskunk) - https://marketplace.visualstudio.com/items?itemName=Natizyskunk.sftp

== Intellisense - Navigation/Auto-complete ==

=== JavaScript Intellisense ===

* Because of dojo style class/method declarations most IDE won't be able to index main JavaScript file properly (i.e. go to definition of function and such). If you manage to get it working in VS code, let us know how.

* There is a way to re-structure code to avoid using this style, but this is not for beginners. Do not use this on your first game! https://en.doc.boardgamearena.com/BGA_Studio_Cookbook#Avoiding_code_in_dojo_declare_style
** There is also a complete example of a "dojo-less" project, it also includes a (incomplete) typescript definition file (.d.ts) for auto-completion of js BGA interfaces https://github.com/elaskavaia/bga-dojoless

* Another way to improve auto-complete and such is to use Typescript and SCSS, this is not for the beginners.
** Original wiki: https://en.doc.boardgamearena.com/Using_Typescript_and_Scss
** There is also 3rd party software that automates typescript template above: [[BGA Type Safe Template]]. It claims to offers a much cleaner initial file, clearer workflow, and nearly complete type and autofill support for whatever you may need.

===PHP Intellisense===

The ide_helper file, included in every project, will help your IDE know the available functions of the framework. This file may be updated automatically on your FTP folder, so don't hesitate to pull it back if it misses something, it might have been updated!

To solve the warning about the material file class members (warning only appears if you use legacy material file)

Option 1) You can define them as class attributes, for example if I have $this->token_types = [...] in the material file I can define them in in the class of game.php

private array $token_types;

Option 2)

Put this line in the settings.json if you using Intelliphense extension to ignore them:

"intelephense.diagnostics.undefinedProperties": false

===Unit testing===

If using phpunit, install it via composer somewhere in home directory, i.e.
cd /home/victoria/php-composer
composer require --dev phpunit/phpunit ^11

Then add this path to include paths in settings

"intelephense.environment.includePaths": [
"/home/victoria/php-composer"
],

See more about unit testing in [[Testing by developer]]

== File Sync==
You can set up your sync using other methods, not related to vscode (such as rsync), if you want to do that see [[Tools_and_tips_of_BGA_Studio#File_Sync]] otherwise see below:

You might rely on your IDE to sync the files with the SFTP server. Each time you "save" a file with your modifications, the IDE will also submit it to the sFTP server. These are instructions for VS Code

*'''Install this extension''' https://marketplace.visualstudio.com/items?itemName=Natizyskunk.sftp (File->Preferences->Extensions ... type SFTP and make sure its by Natizyskunk)

*'''Open VSCode on an empty folder''' that will be the local root of your project.

*Execute Ctrl+Shift+P on Windows/Linux or Cmd+Shift+P on Mac to open the command palette, and the type/run : '''"SFTP: config"''' - the edit will open with json config

* '''Update the json''' as below:

<pre>
{
"name": "BGA",
"host": "1.studio.boardgamearena.com",
"protocol": "sftp",
"port": 2022,
"username": "<your SFTP username>",
"password": "<your SFTP password>",
"remotePath": "/<your project name>/",
"uploadOnSave": true,
"ignore": [
".vscode",
".git",
".DS_Store",
"bga-framework.d.ts",
"* *"
],
"syncOption": {
"skipCreate": false,
"delete": true
}
}
</pre>

* syncOption delete: true - means you want to delete remote file if deleted locally
* syncOption skipCreate: false - means you want to add new files when added locally (false because its reverse option)
* remotePath - do not remove slashes, it is part of the path

===One time only - first sync ===

- Execute Ctrl+Shift+P on Windows/Linux or Cmd+Shift+P on Mac to open the command palette, and the type/run : '''"SFTP: Download Project"'''.

This will download all the files locally.

After initially downloading the project, you can add _ide_helper.php to the "ignore" list. Even though it is needed locally for the IDE to understand BGA-related php code, you will never need to update it.
=== Daily use===

You don't have to do anything else! Each time you modify/save a file in VSCode, it will upload it to the SFTP Server.

To force upload to a server, execute Ctrl+Shift+P -> '''"SFTP: Sync Local -> Remote"'''.

Note: the SFTP sync may fail with a permissions error when create or delete nested folders. To fix this, execute `chmod -R 755 <your directory name>` in your terminal, then force sync to remote.
=== Split settings for version control===
If you want to commit this file to version control, use private key (upload ssh key https://studio.boardgamearena.com/controlpanel) instead and move user/password settings into vscode user settings

I.e. in user setting add this (have to edit settings.js manually, google for location its os specific)
<pre>
"remotefs.remote": {
"bgadev": {
"name": "BGA",
"host": "1.studio.boardgamearena.com",
"protocol": "sftp",
"port": 2022,
"username": "<yourdevusername>",
"privateKeyPath": "~/.ssh/id_rsa",
},
}
</pre>
in project folder sftp.json (replace <yourproject> with project name)
<pre>
{
"remote": "bgadev",
"remotePath": "/<yourproject>/",
"uploadOnSave": true,
"ignore": [
".git"
],
"syncOption": {
"skipCreate": false,
"delete": true
},
"watcher": {
"files": "**/*.{js,css}",
"autoUpload": true,
"autoDelete": true
}
}
</pre>

Note: you don't need watcher section if you don't use code generators, but its needed if you use typescript, scss or similar code generator tools.

==Code Formatter==
I think Prettier has better format, you can install Prettier plugin to do the formatting, for PHP add the following in package.json

"devDependencies": {
"@prettier/plugin-php": "^0.22",
"prettier": "^3.6"
},
"prettier": {
"plugins": ["@prettier/plugin-php"],
"braceStyle": "1tbs",
"printWidth": 140,
"trailingComma": "none"
}

== Code generators==
If you want to run code generators for example for typescript or scss you can install this extension:
*https://marketplace.visualstudio.com/items?itemName=emeraldwalk.RunOnSave

In settings.json add these (example only):
"emeraldwalk.runonsave": {
"commands": [
{
"match": ".*\\.ts$",
"isAsync": true,
"cmd": "npm run build:ts"
},
{
"match": ".*\\.scss$",
"isAsync": true,
"cmd": "npm run build:scss"
}
]
}

In this example <code>build:ts</code> and <code>build:scss</code> are scripts configured via package.json

Another example - you can run php script that will generate material.inc.php from misc/xxx_material.csv
{
"match": "misc/.*material\\.csv$",
"isAsync": true,
"cmd": "php7.4 ${env.HOME}/git/bga-sharedcode/misc/genmat.php ${file}"
}

== User templates==

You can define user template to avoid writing boilerplate code, here is example of php template for states
(it is placed in global location php.json - you can open it from the gui File->Preferences->Configure User Snippets and type php

<pre>
{
"Single player state": {
"prefix": ["state", "playerstate"],

"body": [
"$LINE_COMMENT playerTurn${1:something}",
"${1/(.*)/STATE_PLAYER_TURN_${1:/upcase}/} => [",
"'name' => 'playerTurn${1:something}',",
"'description' => clienttranslate('\\${actplayer} must ${1:something}'),",
"'descriptionmyturn' => clienttranslate('\\${you} must ${1:something}'),",
"'type' => 'activeplayer',",
"'args'=>'arg_playerTurn${1:something}',",
"'action'=>'st_playerTurn${1:something}',",
"'possibleactions' => [ 'playCard', 'pass' ],",
"'transitions' => [",
"'next' => STATE_GAME_TURN_NEXT_PLAYER,",
"'loopback' => ${1/(.*)/STATE_PLAYER_TURN_${1:/upcase}/} ]",
"],"
],

"description": "Create single player state defition, use tab to fill template parameters"
},

"Multiple player state": {
"prefix": ["mstate", "multiplayerstate"],

"body": [
"$LINE_COMMENT mplayerTurn${1:something}",
"${1/(.*)/STATE_MPLAYER_TURN_${1:/upcase}/} => [",
"'name' => 'mplayerTurn${1:something}',",
"'description' => clienttranslate('Other players must ${1:something}'),",
"'descriptionmyturn' => clienttranslate('\\${you} must ${1:something}'),",
"'type' => 'multipleactiveplayer',",
"'args'=>'arg_mplayerTurn${1:something}',",
"'action'=>'stMakeEveryoneActive',",
"'possibleactions' => [ 'playCard', 'pass' ],",
"'transitions' => [",
"'next' => STATE_GAME_TURN_NEXT_MPLAYER,",
"'loopback' => ${1/(.*)/STATE_MPLAYER_TURN_${1:/upcase}/} ]",
"],"
],

"description": "Create multi player state defition, use tab to fill template parameters"
},
"Action in action.php": {
"prefix": ["action"],
"body": [
"public function ${1:actionName}() {",
"\tself::setAjaxMode();",
"\t\\$${2:arg} = self::getArg('${2:arg}', AT_posint, false, 0);",
"\t\\$this->game->action_${1:actionName}(\\$${2:arg});",
"\tself::ajaxResponse();",
"}"
]
},
"Player loop in game.php": {
"prefix": ["players"],
"body": [
"\\$players = \\$this->loadPlayersBasicInfos();",
"foreach (\\$players as \\$player_id => \\$player_info) {",
"${1}",
"}"
]
}

}
</pre>
[[Category:Studio]]

Tutorial hearts

2025-10-05T04:18:02Z

ShaharHarshuv: /* Game Database and Game Initialization */

{{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]]).
* Know the rules for Hearts
* 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]

== 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. 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.
</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 full game can be found in your FTP home folder, after getting read-only access: https://en.doc.boardgamearena.com/First_steps_with_BGA_Studio#Set_up_dev_environment_ide,_editor_and_File_Sync

== 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://github.com/elaskavaia/bga-heartsla/blob/4b3a73eeb5acae961ade18473af119e8ce8d1a8f/img/cards.jpg hearts img/cards.jpg] into img/ folder of your project.
<blockquote>There are better quality deck of cards image at https://en.doc.boardgamearena.com/Common_board_game_elements_image_resources</blockquote>

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>
document.getElementById('game_play_area').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 (the image slightly obsolete, you may see more stuff there and different prompt).

[[File:Heartsla-tpl2.png]]

Now lets add a card into the hand, just so you can feel it. Edit the html string we inserted earlier and a playertablecard div inside a hand div
<pre>
...
<div id="myhand">
<div class="playertablecard"></div>
</div>
...
</pre>

Edit .css file
<pre>
.playertablecard {
display: inline-block;
position: relative;
margin-top: 5px;
width: 72px;
height: 96px;
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:

[[File:Heartsla-tpl3.png]]

Awesome! Now lets do the rest of layout.

Note: If you don't see the card a) check it was synced to remote folder b) force reload page

Let's complete the template string we created for the hand. You template should have this code, just leave it there
<pre>

// Example to add a div on the game area
document.getElementById("game_play_area").insertAdjacentHTML("beforeend",
`
<div id="player-tables"></div>
`
);
</pre>

Then change the following template code to this
<pre>
// Setting up player boards
var numPlayers = Object.keys(gamedatas.players).length;
Object.values(gamedatas.players).forEach((player, index) => {
document.getElementById("player-tables").insertAdjacentHTML(
"beforeend",
`
<div class="playertable whiteblock playertable_${DIRECTIONS[numPlayers][index]}">
<div class="playertablename" style="color:#${player.color};"><span class="dealer_token" id="dealer_token_p${player.id}">🃏 </span>${player.name}</div>
<div class="playertablecard" id="playertablecard_${player.id}"></div>
<div class="playertablename" id="hand_score_wrap_${player.id}"><span class="hand_score_label"></span> <span id="hand_score_${player.id}"></span></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
heartslav.js:68 Uncaught (in promise) ReferenceError: DIRECTIONS is not defined

For this new code to work, we need to add a constant at the beginning of the JS file, defining the expected position of each player (right after copyright comment):
<pre>
const DIRECTIONS = {
3: ['S', 'W', 'E'],
4: ['S', 'W', 'N', 'E'],
};
</pre>

Reload. If everything went well you should see this:

[[File:Hearts all rows.png|alt=Display a list of all players, with a dummy card in each position]]

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>
/** Table layout **/

#player-tables {
position: relative;
width: 710px;
height: 340px;
}

.playertablename {
font-weight: bold;
}

.playertable {
position: absolute;
text-align: center;
width: 180px;
height: 130px;
}

.playertable_N {
left: 50%;
top: 0px;
margin-left: -90px; /* half of 180 */
}
.playertable_S {
left: 50%;
bottom: 0px;
margin-left: -90px; /* half of 180 */
}
.playertable_W {
left: 0px;
top: 50%;
margin-top: -55px; /* half of 130 */
}
.playertable_E {
right: 0px;
top: 50%;
margin-top: -55px; /* half of 130 */
}
</pre>

Now you force Reload and you should see this:
[[File:Heartsla-tpl5.png]]

This is almost all we need for graphics and layout, there are few tweaks left there but lets do some more heavy lifting now.

<i>Note: if you did not see changes you may have not force reloaded, force means you use Ctrl+F5 or Cltr+Shift-R, if you don't "force" browser will use cached version of images! Which is not what you just changed</i>

<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 JS Stock ==

The BGA framework provides a few out of the box classes to deal with cards. The client side
contains a class called [[Stock]] and it can be used for any dynamic html "pieces" management that uses
common sprite images. 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 13x4 grid of images stitched together,
which is a very efficient way to transport images. So we will use the Stock class to mark up these images and create
"card" divs for us.

First, we need to add '''ebg/stock''' as a dependency in the .js file:
<pre>
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/stock" /// <==== HERE, don't forget comma before
],
</pre>

Then add this to the Javascript constructor, this will define size of our cards
<pre>
console.log('hearts constructor');
this.cardwidth = 72;
this.cardheight = 96;
</pre>

The stock is initialized in the Javascript "setup" method, after we have created the "myhand" element", like this:
<pre>
// TODO: Set up your game interface here, according to "gamedatas"

// Player hand
this.playerHand = new ebg.stock(); // new stock object for hand
this.playerHand.create( this, $('myhand'), this.cardwidth, this.cardheight );
</pre>

As parameters of the "create" method, we provided the width/height of an item (a card), and the container div "myhand" - which is an id of "div" element we have created before.

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

Here's how we tell stock what item types to display (add after .create):
<pre>
this.playerHand.image_items_per_row = 13; // 13 images per row

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

And add this function to the utilities section
<pre>
// Get card unique identifier based on its color and value
getCardUniqueId : function(color, value) {
return (color - 1) * 13 + (value - 2);
},
</pre>

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

Note: we need to generate a unique ID for each type of card based on its color and value. For that we create a function '''getCardUniqueId'''. The type is the unique identifier of the TYPE of the card, e.g., the queen of spades encoded as an integer. If our deck had 2 standard card decks we would have had 2 queens of spades; they would share the same type and the same image but would have different ids. NOTE: It's unfortunate that they named this '''getCardUniqueId'''; it should have been '''getCardUniqueType''', because it really isn't an id, but a TYPE of card. The type of the item should either be a reversible function of its properties (i.e., kind of suite * 13 + value) or just an enumerator described in material.inc.php. In this specific case it's a synthetic type id, which also the same as the number of the card in the sprite image (i.e., if you enumerate each image in sprite going left to right, then top to bottom).

Now let's add the 5 of Hearts to the player's hand just for fun (this code will go in setup method after types initialization):

<pre>
// 2 = hearts, 5 is 5, and 42 is the card id, which normally would come from db
this.playerHand.addToStockWithId( this.getCardUniqueId( 2, 5 ), 42 );
</pre>

This will add the card with id 42 and type 16 ( (2-1)*13+(5-2)=16 ).

Note that number 16 would not be something you can see in database, Deck database will have separate field for type and type_arg where type is suite and type_arg is number, so its not the same thing, but you can use same formula to convert. Number 42 on the other hand would be id field in database. But we get to database in the later section.

If you reload now you should see the 5 of hearts in "your hand".

You may see some weird graphics glitches - its because we did not remove our hack with background from .css yet. You can go to .css file now and remove line with comment "temp hack to see it".

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, after this.playerHand is initialised:

dojo.connect( this.playerHand, 'onChangeSelection', this, 'onPlayerHandSelectionChanged' );

Then find the Player's action comment section in .js file and add a handler after the comment:

<pre>
///////////////////////////////////////////////////
//// Player's action

onPlayerHandSelectionChanged: function () {
var items = this.playerHand.getSelectedItems();

if (items.length > 0) {
if (this.checkAction("actPlayCard", true)) {
// Can play a card

var card_id = items[0].id;
console.log("on playCard " + card_id);

this.playerHand.unselectAll();
} else if (this.checkAction("actGiveCards")) {
// Can give cards => let the player select some cards
} else {
this.playerHand.unselectAll();
}
}
},
</pre>

''Note : If you already have an example handler <code>onCardClick: function( card_id )</code>, go ahead and remove that handler, it is a duplicate of what we are implementing in this tutorial and may cause issues later on.''

The function name of the handler is 4th parameter of the dojo.connect function. Make sure you spell it correctly or there will be unpredictable effects.

Now if you reload, open the Javascript Console (F12), and then click on the card in My Hand, you should see:
on playCard 42
printed on the console

''Note : You need to be the active player to have rights to play a card and so log your message in the console''

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

To modify the schema, first exit your existing game(s). Open '''dbmodel.sql''' file and uncomment the card table creation.

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

This is the "card" table which will be managed by the Deck php class.

In addition we want a little piece of information in the players table:

-- add info about first player
ALTER TABLE `player` ADD `player_first` BOOLEAN NOT NULL DEFAULT '0';

Not sure why they put this into the player table, as we could use a global db variable to hold first player as easily.
But I am just following the existing code more-or-less. It is not recommended to modify player table in general.

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>
parent::__construct();
$this->initGameStateLabels(
[
"currentHandType" => 10,
"trickColor" => 11,
"alreadyPlayedHearts" => 12,
]
);;

$this->cards = $this->deckFactory->createDeck('card');
</pre>

If you see errors in IDE its because we also have to declared "cards" as class member, add protected $cards; before the contructor.

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:

* "trickColor": numbers from 1 to 4 that map to card suit (not sure why it's called color; maybe it's a translation from French);
* "alreadyPlayedHearts": a boolean flag (0 or 1) indicating whether somebody used hearts on the trick;
* "currentHandType": stores the value to indicate who to give cards to during exchange.

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->init( "foo" )</i>

Note: lower in the code there is a line that needs to be removed in order for the game to start. Search for it and remove it now.
$this->setGameStateInitialValue("my_first_global_variable", 0);

Since we changed the db, 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>

Code Rev [https://github.com/elaskavaia/bga-heartsla/tree/acd1926a6c09dc9afd0752cb6b78eef17c5dfe5c]

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 "Start the game initialization" comment.
<pre>
// Init global values with their initial values

// Note: hand types: 0 = give 3 cards to player on the left
// 1 = give 3 cards to player on the right
// 2 = give 3 cards to player opposite
// 3 = keep cards
$this->setGameStateInitialValue( 'currentHandType', 0 );

// Set current trick color to zero (= no trick color)
$this->setGameStateInitialValue( 'trickColor', 0 );

// Mark if we already played hearts during this hand
$this->setGameStateInitialValue( 'alreadyPlayedHearts', 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.
<pre>
// Create cards
$cards = [];
foreach (self::$CARD_SUITS as $suit => $suit_info) {
// spade, heart, diamond, club
foreach (self::$CARD_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 $this->colors.
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

<pre>
self::$CARD_SUITS = [
1 => [
'name' => clienttranslate('Spade'),
],
2 => [
'name' => clienttranslate('Heart'),
],
3 => [
'name' => clienttranslate('Club'),
],
4 => [
'name' => clienttranslate('Diamond'),
]
];

self::$CARD_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 declared these fields in the class
private static array $CARD_SUITS;
private static array $CARD_TYPES;

== Full game model synchronisation ==

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. 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', $current_player_id );

// 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 .js file in the setup function (which is the receiver of getAllDatas) replace our hack of putting 5 of Hearts directly into the hand with:

<pre>
// Cards in player's hand
for ( var i in this.gamedatas.hand) {
var card = this.gamedatas.hand[i];
var color = card.type;
var value = card.type_arg;
this.playerHand.addToStockWithId(this.getCardUniqueId(color, value), card.id);
}

// Cards played on table
for (i in this.gamedatas.cardsontable) {
var card = this.gamedatas.cardsontable[i];
var color = card.type;
var value = card.type_arg;
var player_id = card.location_arg;
this.playCardOnTable(player_id, color, value, card.id);
}
</pre>

This should show hand and tableau cards now, except we are missing the '''playCardOnTable''' function. So find the '''getCardUniqueId''' function which
should be in the utilities section and add this after it:

<pre>
playCardOnTable : function(player_id, color, value, card_id) {
// player_id => direction
this.addTableCard(value, color, player_id, player_id);

if (player_id != this.player_id) {
// Some opponent played a card
// Move card from player panel
this.placeOnObject('cardontable_' + player_id, 'overall_player_board_' + player_id);
} else {
// You played a card. If it exists in your hand, move card from there and remove
// corresponding item

if ($('myhand_item_' + card_id)) {
this.placeOnObject('cardontable_' + player_id, 'myhand_item_' + card_id);
this.playerHand.removeFromStockById(card_id);
}
}

// In any case: move it to its final destination
this.slideToObject('cardontable_' + player_id, 'playertablecard_' + player_id).play();
},
</pre>

For this to work we also need to define the addTableCard
<pre>
addTableCard(value, color, card_player_id, playerTableId) {
const x = value - 2;
const y = color - 1;
document.getElementById('playertablecard_' + playerTableId).insertAdjacentHTML('beforeend', `
<div class="card cardontable" id="cardontable_${card_player_id}" style="background-position:-${x}00% -${y}00%"></div>
`);
},
</pre>

What this does is basically create another card object, because if it is not our card it's not in our hand (Stock) so
we have to create it out of thin air. Now we have an object with an id of 'cardontable_' + player_id. Depending
on who is playing it we either place it on the player miniboard or in hand (and remove it from hand stock). Then we animate the card move.

We also should fix our .css file now to add style for cardontable and REMOVE background for playertablecard which really is a placeholder div and not a card. (Don't miss the remove step; it will be all screwy if you do!)

<pre>
.playertablecard {
display: inline-block;
position: relative;
margin-top: 5px;
width: 72px;
height: 96px;
/* we remove background-image here */
}

/*** cards on table ***/

.cardontable {
position: absolute;
width: 72px;
height: 96px;
background-image: url('img/cards.jpg');
}
</pre>

Now to test that it actually works let's deal cards to players during game initialization:

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 ) {
$cards = $this->cards->pickCards(13, 'deck', $player_id);
}
</pre>

Now when you start the game you should see 13 cards in your hand!

We just need to hook-up clicking on card and test if our playCardOnTable works.

Find onPlayerHandSelectionChanged function in the JS file, we should have logging there like console.log("on playCard "+card_id);
So after that insert this (Note: this code is for testing we will replace it with server interaction after we test it.):
<pre>
console.log("on playCard "+card_id);
// type is (color - 1) * 13 + (value - 2)
var type = items[0].type;
var color = Math.floor(type / 13) + 1;
var value = type % 13 + 2;

this.playCardOnTable(this.player_id,color,value,card_id);
</pre>
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]]

Code Rev [https://github.com/elaskavaia/bga-heartsla/tree/0ed80e254a6d0c29f267b308d1c2016db90fd4f6]

== State Machine ==

Now we need to create a game state machine. So the states are (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 is selected who will start a new trick ("newTrick")
* 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) ("nextHand")

The state handling spread across multiple files, so you have to make sure all pieces are connected together.
The state machine states.php defines all the states, and function handlers on php side in a form of string,
and if any of these functions are not implemented it would be very hard to debug because it will break in random places.

So .states.php (remove all template states and replace with these)

<pre>
$machinestates = array(
/// New hand
2 => array(
"name" => "newHand",
"description" => "",
"type" => "game",
"action" => "stNewHand",
"updateGameProgression" => true,
"transitions" => array( "" => 30 )
),

21 => array(
"name" => "giveCards",
"description" => clienttranslate('Some players must choose 3 cards to give to ${direction}'),
"descriptionmyturn" => clienttranslate('${you} must choose 3 cards to give to ${direction}'),
"type" => "multipleactiveplayer",
"action" => "stGiveCards",
"args" => "argGiveCards",
"possibleactions" => array( "actGiveCards" ),
"transitions" => array( "giveCards" => 22, "skip" => 22 )
),

22 => array(
"name" => "takeCards",
"description" => "",
"type" => "game",
"action" => "stTakeCards",
"transitions" => array( "startHand" => 30, "skip" => 30 )
),

// Trick

30 => array(
"name" => "newTrick",
"description" => "",
"type" => "game",
"action" => "stNewTrick",
"transitions" => array( "" => 31 )
),
31 => array(
"name" => "playerTurn",
"description" => clienttranslate('${actplayer} must play a card'),
"descriptionmyturn" => clienttranslate('${you} must play a card'),
"type" => "activeplayer",
"possibleactions" => array( "actPlayCard" ),
"transitions" => array( "playCard" => 32 )
),
32 => array(
"name" => "nextPlayer",
"description" => "",
"type" => "game",
"action" => "stNextPlayer",
"transitions" => array( "nextPlayer" => 31, "nextTrick" => 30, "endHand" => 40 )
),

// End of the hand (scoring, etc...)
40 => array(
"name" => "endHand",
"description" => "",
"type" => "game",
"action" => "stEndHand",
"transitions" => array( "nextHand" => 2, "endGame" => 99 )
),

);
</pre>

The full details on these fields are in [[Your_game_state_machine:_states.inc.php]].

But basically we have Player states, in which a human player has to perform an "action" by pressing some button in the UI or selecting some game item, which will trigger js handler, which will do an ajax call to the server.

To make it run we have to define all the handler functions that we referenced in states, which are - one function for state arguments argGiveCards, 4 functions for robot states (where the game performs some action)
and 1 function for player actions handling.
In Game.php, find 'Game state arguments' section and paste this in:
<pre>
function argGiveCards() {
return [];
}
</pre>

This normally passes some parameters to states, but we don't need anything yet. It's good to have a placeholder there anyway, so we can fix it later.
Important: even when it's a stub, this function must return an array not a scalar.

Let's do stubs for other functions, find the game state actions section in Game.php file and insert these (replace all st* method defined in template)
<pre>
function stNewHand() {
// Take back all cards (from any location => null) to deck
$this->cards->moveAllCardsInLocation(null, "deck");
$this->cards->shuffle('deck');
// Deal 13 cards to each players
// Create deck, shuffle it and give 13 initial cards
$players = $this->loadPlayersBasicInfos();
foreach ( $players as $player_id => $player ) {
$cards = $this->cards->pickCards(13, 'deck', $player_id);
// Notify player about his cards
$this->notify->player($player_id, 'newHand', '', array ('cards' => $cards ));
}
$this->setGameStateValue('alreadyPlayedHearts', 0);
$this->gamestate->nextState("");
}

function stNewTrick() {
// New trick: active the player who wins the last trick, or the player who own the club-2 card
// Reset trick color to 0 (= no color)
$this->setGameStateInitialValue('trickColor', 0);
$this->gamestate->nextState();
}

function stNextPlayer() {
// Active next player OR end the trick and go to the next trick OR end the hand
if ($this->cards->countCardInLocation('cardsontable') == 4) {
// This is the end of the trick
// Move all cards to "cardswon" of the given player
$best_value_player_id = $this->activeNextPlayer(); // TODO figure out winner of trick
$this->cards->moveAllCardsInLocation('cardsontable', 'cardswon', null, $best_value_player_id);

if ($this->cards->countCardInLocation('hand') == 0) {
// End of the hand
$this->gamestate->nextState("endHand");
} else {
// End of the trick
$this->gamestate->nextState("nextTrick");
}
} else {
// Standard case (not the end of the trick)
// => just active the next player
$player_id = $this->activeNextPlayer();
$this->giveExtraTime($player_id);
$this->gamestate->nextState('nextPlayer');
}
}

function stEndHand() {
$this->gamestate->nextState("nextHand");
}

</pre>
Important: All state actions game or player must end with state transition (or thrown exception). Also make sure it's ONLY one state transition,
if you accidentally fall through after state transition and do another one it will be a real mess and head scratching for long time.

Now find 'player actions' section and paste this code there (replace all existing act* functions)
<pre>
function actPlayCard(int $card_id) {
$player_id = $this->getActivePlayerId();
throw new \BgaUserException(clienttranslate('Not implemented: ${player_id} plays ${card_id}'), [
"player_id" => "$player_id",
"card_id" => $card_id,
]);

}
</pre>
We won't implement it yet but throw an exception which we will see if interaction is working properly

If your game is running you have to exit it. When we change state machine in the middle of the game usually it won't be good.

Now the game should start but it would not be any different than before because we have to implement actual interactions.
It's good to check if it's still working though (and if it was running before you have to exit because we changed state machine and normally it will break stuff).

NOTE: When you play a card, you will not yet get the "Not implemented" message. That is added in the next section.

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
<pre>
onUpdateActionButtons: function (stateName, args) {
console.log("onUpdateActionButtons: " + stateName, args);

if (this.isCurrentPlayerActive()) {
switch (stateName) {
case "playerTurn":
break;
}
}
},
</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.

Eventhough we can it ajax call the API now called "bgaPerformAction" and this is what you should be using.

So in .js code replace onPlayerHandSelectionChanged with
<pre>
onPlayerHandSelectionChanged : function() {
var items = this.playerHand.getSelectedItems();

if (items.length > 0) {
var action = 'actPlayCard';
if (this.checkAction(action, true)) {
// Can play a card
var card_id = items[0].id;
this.bgaPerformAction(action, {
card_id : card_id,
});

this.playerHand.unselectAll();
} else if (this.checkAction('actGiveCards')) {
// Can give cards => let the player select some cards
} else {
this.playerHand.unselectAll();
}
}
},
</pre>

Now when you click on card you should get a server response: Not implemented...

Lets implement it, in Game.php
<pre>

function actPlayCard(int $card_id) {
$player_id = $this->getActivePlayerId();
$this->cards->moveCard($card_id, 'cardsontable', $player_id);
// XXX check rules here
$currentCard = $this->cards->getCard($card_id);
// And notify
$this->notify->all('playCard', clienttranslate('${player_name} plays ${value_displayed} ${color_displayed}'), array (
'i18n' => array ('color_displayed','value_displayed' ),'card_id' => $card_id,'player_id' => $player_id,
'player_name' => $this->getActivePlayerName(),
'value' => $currentCard ['type_arg'],
'value_displayed' => self::$CARD_TYPES [$currentCard ['type_arg']] ['name'],
'color' => $currentCard ['type'],
'color_displayed' => self::$CARD_SUITS [$currentCard ['type']] ['name'] ));
// Next player
$this->gamestate->nextState('playCard');
}

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

<pre>
setupNotifications : function() {
console.log('notifications subscriptions setup');
// table of notif type to delay in milliseconds
const notifs = [
['newHand', 1],
['playCard', 100],
];

notifs.forEach((notif) => {
dojo.subscribe(notif[0], this, `notif_${notif[0]}`);
this.notifqueue.setSynchronous(notif[0], notif[1]);
});

},

notif_newHand : function(notif) {
// We received a new full hand of 13 cards.
this.playerHand.removeAll();

for ( var i in notif.args.cards) {
var card = notif.args.cards[i];
var color = card.type;
var value = card.type_arg;
this.playerHand.addToStockWithId(this.getCardUniqueId(color, value), card.id);
}
},

notif_playCard : function(notif) {
// Play a card on the table
this.playCardOnTable(notif.args.player_id, notif.args.color, notif.args.value, notif.args.card_id);
},
</pre>

Now it actually works through the server when you click on card - the move is recorded. If you test it now 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 we need to send notification about it
and have a handler for it

So in Game.php file add notification in stNextPlayer function after moveAllCardsInLocation call:

<pre>
// Notify
// 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 = $this->loadPlayersBasicInfos();
$this->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']
) );
$this->notify->all( 'giveAllCardsToPlayer','', array(
'player_id' => $best_value_player_id
) );
</pre>

And in .js file add 2 more notification handlers.

This is to subscribe in setupNotifications function
<pre>
const notifs = [
...
['trickWin', 1000],
['giveAllCardsToPlayer', 600],
];
</pre>

And these are handlers
<pre>
notif_trickWin : function(notif) {
// We do nothing here (just wait in order players can view the 4 cards played before they're gone.
},
notif_giveAllCardsToPlayer : function(notif) {
// Move all cards on table to given table, then destroy them
var winner_id = notif.args.player_id;
for ( var player_id in this.gamedatas.players) {
var anim = this.slideToObject('cardontable_' + player_id, 'overall_player_board_' + winner_id);
dojo.connect(anim, 'onEnd', function(node) {
dojo.destroy(node);
});
anim.play();
}
},
</pre>

So 'trickWin' notification does not do much except it will delay the processing of next notification by 1 second (1000 ms)
and it will log the message (that happens independently of what handler does).
<i>Note: if on the other hand you don't want to log but want to do something else, send an empty message</i>

Now after the trick you see all cards move towards the "player's stash".

== 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 'trickColor' which we already conveniently created.

In Game.php file find the actPlayCard function and add this before notify functions
$currentTrickColor = $this->getGameStateValue( 'trickColor' ) ;
if( $currentTrickColor == 0 )
$this->setGameStateValue( 'trickColor', $currentCard['type'] );

This will make sure we remember the first suit being played, now to use it modify the stNextPlayer function to fix our TODO comment
<pre>
function stNextPlayer() {
// Active next player OR end the trick and go to the next trick OR end the hand
if ($this->cards->countCardInLocation('cardsontable') == 4) {
// This is the end of the trick
$cards_on_table = $this->cards->getCardsInLocation('cardsontable');
$best_value = 0;
$best_value_player_id = null;
$currentTrickColor = $this->getGameStateValue('trickColor');
foreach ( $cards_on_table as $card ) {
// Note: type = card color
if ($card ['type'] == $currentTrickColor) {
if ($best_value_player_id === null || $card ['type_arg'] > $best_value) {
$best_value_player_id = $card ['location_arg']; // Note: location_arg = player who played this card on table
$best_value = $card ['type_arg']; // Note: type_arg = value of the card
}
}
}

// Active this player => he's the one who starts the next trick
$this->gamestate->changeActivePlayer( $best_value_player_id );

// Move all cards to "cardswon" of the given player
$this->cards->moveAllCardsInLocation('cardsontable', 'cardswon', null, $best_value_player_id);

// Notify
// ... same code here 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, also
we want to show that in the log.
In addition scoring can be shown in [[Game_interface_logic:_yourgamename.js#Scoring_dialogs|Scoring Dialog]] using tableWindow notification, but it is a tutorial on its own and you can do it as homework (it is part of original heart game).

so in Game.php our stEndHand function will look like

<pre>
function stEndHand() {
// Count and score points, then end the game or go to the next hand.
$players = $this->loadPlayersBasicInfos();
// Gets all "hearts" + queen of spades

$player_to_points = array ();
foreach ( $players as $player_id => $player ) {
$player_to_points [$player_id] = 0;
}
$cards = $this->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) {
$this->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 ($this->playerScore->getMin() <= -100) {
// Trigger the end of the game !
$this->gamestate->nextState("endGame");
return;
}

$this->gamestate->nextState("nextHand");
}
</pre>

So it should more less work now, including end of game condition. Try to play it!

== Additional stuff ==

The following things were not implemented and can add them yourself by looking at the code of original hearts game:

* Remove debug code from setupNewGame to deal cards, cards are now dealt in stNewHand state handler
* Rule checking and rule enforcements in actPlayCard function
* Start scoring with 100 points each and end when <= 0
* Fix scoring rules with Q of spades and 26 point reverse scoring
* First player one with 2 club
* Add progress handling
* 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

2025-10-05T03:40:19Z

ShaharHarshuv: Update part that related to older .tpl workflow

{{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]]).
* Know the rules for Hearts
* 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]

== 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. 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.
</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 full game can be found in your FTP home folder, after getting read-only access: https://en.doc.boardgamearena.com/First_steps_with_BGA_Studio#Set_up_dev_environment_ide,_editor_and_File_Sync

== 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://github.com/elaskavaia/bga-heartsla/blob/4b3a73eeb5acae961ade18473af119e8ce8d1a8f/img/cards.jpg hearts img/cards.jpg] into img/ folder of your project.
<blockquote>There are better quality deck of cards image at https://en.doc.boardgamearena.com/Common_board_game_elements_image_resources</blockquote>

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>
document.getElementById('game_play_area').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 (the image slightly obsolete, you may see more stuff there and different prompt).

[[File:Heartsla-tpl2.png]]

Now lets add a card into the hand, just so you can feel it. Edit the html string we inserted earlier and a playertablecard div inside a hand div
<pre>
...
<div id="myhand">
<div class="playertablecard"></div>
</div>
...
</pre>

Edit .css file
<pre>
.playertablecard {
display: inline-block;
position: relative;
margin-top: 5px;
width: 72px;
height: 96px;
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:

[[File:Heartsla-tpl3.png]]

Awesome! Now lets do the rest of layout.

Note: If you don't see the card a) check it was synced to remote folder b) force reload page

Let's complete the template string we created for the hand. You template should have this code, just leave it there
<pre>

// Example to add a div on the game area
document.getElementById("game_play_area").insertAdjacentHTML("beforeend",
`
<div id="player-tables"></div>
`
);
</pre>

Then change the following template code to this
<pre>
// Setting up player boards
var numPlayers = Object.keys(gamedatas.players).length;
Object.values(gamedatas.players).forEach((player, index) => {
document.getElementById("player-tables").insertAdjacentHTML(
"beforeend",
`
<div class="playertable whiteblock playertable_${DIRECTIONS[numPlayers][index]}">
<div class="playertablename" style="color:#${player.color};"><span class="dealer_token" id="dealer_token_p${player.id}">🃏 </span>${player.name}</div>
<div class="playertablecard" id="playertablecard_${player.id}"></div>
<div class="playertablename" id="hand_score_wrap_${player.id}"><span class="hand_score_label"></span> <span id="hand_score_${player.id}"></span></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
heartslav.js:68 Uncaught (in promise) ReferenceError: DIRECTIONS is not defined

For this new code to work, we need to add a constant at the beginning of the JS file, defining the expected position of each player (right after copyright comment):
<pre>
const DIRECTIONS = {
3: ['S', 'W', 'E'],
4: ['S', 'W', 'N', 'E'],
};
</pre>

Reload. If everything went well you should see this:

[[File:Hearts all rows.png|alt=Display a list of all players, with a dummy card in each position]]

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>
/** Table layout **/

#player-tables {
position: relative;
width: 710px;
height: 340px;
}

.playertablename {
font-weight: bold;
}

.playertable {
position: absolute;
text-align: center;
width: 180px;
height: 130px;
}

.playertable_N {
left: 50%;
top: 0px;
margin-left: -90px; /* half of 180 */
}
.playertable_S {
left: 50%;
bottom: 0px;
margin-left: -90px; /* half of 180 */
}
.playertable_W {
left: 0px;
top: 50%;
margin-top: -55px; /* half of 130 */
}
.playertable_E {
right: 0px;
top: 50%;
margin-top: -55px; /* half of 130 */
}
</pre>

Now you force Reload and you should see this:
[[File:Heartsla-tpl5.png]]

This is almost all we need for graphics and layout, there are few tweaks left there but lets do some more heavy lifting now.

<i>Note: if you did not see changes you may have not force reloaded, force means you use Ctrl+F5 or Cltr+Shift-R, if you don't "force" browser will use cached version of images! Which is not what you just changed</i>

<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 JS Stock ==

The BGA framework provides a few out of the box classes to deal with cards. The client side
contains a class called [[Stock]] and it can be used for any dynamic html "pieces" management that uses
common sprite images. 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 13x4 grid of images stitched together,
which is a very efficient way to transport images. So we will use the Stock class to mark up these images and create
"card" divs for us.

First, we need to add '''ebg/stock''' as a dependency in the .js file:
<pre>
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/stock" /// <==== HERE, don't forget comma before
],
</pre>

Then add this to the Javascript constructor, this will define size of our cards
<pre>
console.log('hearts constructor');
this.cardwidth = 72;
this.cardheight = 96;
</pre>

The stock is initialized in the Javascript "setup" method, after we have created the "myhand" element", like this:
<pre>
// TODO: Set up your game interface here, according to "gamedatas"

// Player hand
this.playerHand = new ebg.stock(); // new stock object for hand
this.playerHand.create( this, $('myhand'), this.cardwidth, this.cardheight );
</pre>

As parameters of the "create" method, we provided the width/height of an item (a card), and the container div "myhand" - which is an id of "div" element we have created before.

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

Here's how we tell stock what item types to display (add after .create):
<pre>
this.playerHand.image_items_per_row = 13; // 13 images per row

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

And add this function to the utilities section
<pre>
// Get card unique identifier based on its color and value
getCardUniqueId : function(color, value) {
return (color - 1) * 13 + (value - 2);
},
</pre>

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

Note: we need to generate a unique ID for each type of card based on its color and value. For that we create a function '''getCardUniqueId'''. The type is the unique identifier of the TYPE of the card, e.g., the queen of spades encoded as an integer. If our deck had 2 standard card decks we would have had 2 queens of spades; they would share the same type and the same image but would have different ids. NOTE: It's unfortunate that they named this '''getCardUniqueId'''; it should have been '''getCardUniqueType''', because it really isn't an id, but a TYPE of card. The type of the item should either be a reversible function of its properties (i.e., kind of suite * 13 + value) or just an enumerator described in material.inc.php. In this specific case it's a synthetic type id, which also the same as the number of the card in the sprite image (i.e., if you enumerate each image in sprite going left to right, then top to bottom).

Now let's add the 5 of Hearts to the player's hand just for fun (this code will go in setup method after types initialization):

<pre>
// 2 = hearts, 5 is 5, and 42 is the card id, which normally would come from db
this.playerHand.addToStockWithId( this.getCardUniqueId( 2, 5 ), 42 );
</pre>

This will add the card with id 42 and type 16 ( (2-1)*13+(5-2)=16 ).

Note that number 16 would not be something you can see in database, Deck database will have separate field for type and type_arg where type is suite and type_arg is number, so its not the same thing, but you can use same formula to convert. Number 42 on the other hand would be id field in database. But we get to database in the later section.

If you reload now you should see the 5 of hearts in "your hand".

You may see some weird graphics glitches - its because we did not remove our hack with background from .css yet. You can go to .css file now and remove line with comment "temp hack to see it".

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, after this.playerHand is initialised:

dojo.connect( this.playerHand, 'onChangeSelection', this, 'onPlayerHandSelectionChanged' );

Then find the Player's action comment section in .js file and add a handler after the comment:

<pre>
///////////////////////////////////////////////////
//// Player's action

onPlayerHandSelectionChanged: function () {
var items = this.playerHand.getSelectedItems();

if (items.length > 0) {
if (this.checkAction("actPlayCard", true)) {
// Can play a card

var card_id = items[0].id;
console.log("on playCard " + card_id);

this.playerHand.unselectAll();
} else if (this.checkAction("actGiveCards")) {
// Can give cards => let the player select some cards
} else {
this.playerHand.unselectAll();
}
}
},
</pre>

''Note : If you already have an example handler <code>onCardClick: function( card_id )</code>, go ahead and remove that handler, it is a duplicate of what we are implementing in this tutorial and may cause issues later on.''

The function name of the handler is 4th parameter of the dojo.connect function. Make sure you spell it correctly or there will be unpredictable effects.

Now if you reload, open the Javascript Console (F12), and then click on the card in My Hand, you should see:
on playCard 42
printed on the console

''Note : You need to be the active player to have rights to play a card and so log your message in the console''

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

To modify the schema, first exit your existing game(s). Open '''dbmodel.sql''' file and uncomment the card table creation.

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

This is the "card" table which will be managed by the Deck php class.

In addition we want a little piece of information in the players table:

-- add info about first player
ALTER TABLE `player` ADD `player_first` BOOLEAN NOT NULL DEFAULT '0';

Not sure why they put this into the player table, as we could use a global db variable to hold first player as easily.
But I am just following the existing code more-or-less. It is not recommended to modify player table in general.

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>
parent::__construct();
$this->initGameStateLabels( array(
"currentHandType" => 10,
"trickColor" => 11,
"alreadyPlayedHearts" => 12,
) );

$this->cards = $this->deckFactory->createDeck('card');
</pre>

If you see errors in IDE its because we also have to declared "cards" as class member, add protected $cards; before the contructor.

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:

* "trickColor": numbers from 1 to 4 that map to card suit (not sure why it's called color; maybe it's a translation from French);
* "alreadyPlayedHearts": a boolean flag (0 or 1) indicating whether somebody used hearts on the trick;
* "currentHandType": stores the value to indicate who to give cards to during exchange.

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->init( "foo" )</i>

Note: lower in the code there is a line that needs to be removed in order for the game to start. Search for it and remove it now.
$this->setGameStateInitialValue("my_first_global_variable", 0);

Since we changed the db, 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>

Code Rev [https://github.com/elaskavaia/bga-heartsla/tree/acd1926a6c09dc9afd0752cb6b78eef17c5dfe5c]

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 "Start the game initialization" comment.
<pre>
// Init global values with their initial values

// Note: hand types: 0 = give 3 cards to player on the left
// 1 = give 3 cards to player on the right
// 2 = give 3 cards to player opposite
// 3 = keep cards
$this->setGameStateInitialValue( 'currentHandType', 0 );

// Set current trick color to zero (= no trick color)
$this->setGameStateInitialValue( 'trickColor', 0 );

// Mark if we already played hearts during this hand
$this->setGameStateInitialValue( 'alreadyPlayedHearts', 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.
<pre>
// Create cards
$cards = [];
foreach (self::$CARD_SUITS as $suit => $suit_info) {
// spade, heart, diamond, club
foreach (self::$CARD_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 $this->colors.
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

<pre>
self::$CARD_SUITS = [
1 => [
'name' => clienttranslate('Spade'),
],
2 => [
'name' => clienttranslate('Heart'),
],
3 => [
'name' => clienttranslate('Club'),
],
4 => [
'name' => clienttranslate('Diamond'),
]
];

self::$CARD_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 declared these fields in the class
private static array $CARD_SUITS;
private static array $CARD_TYPES;

== Full game model synchronisation ==

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. 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', $current_player_id );

// 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 .js file in the setup function (which is the receiver of getAllDatas) replace our hack of putting 5 of Hearts directly into the hand with:

<pre>
// Cards in player's hand
for ( var i in this.gamedatas.hand) {
var card = this.gamedatas.hand[i];
var color = card.type;
var value = card.type_arg;
this.playerHand.addToStockWithId(this.getCardUniqueId(color, value), card.id);
}

// Cards played on table
for (i in this.gamedatas.cardsontable) {
var card = this.gamedatas.cardsontable[i];
var color = card.type;
var value = card.type_arg;
var player_id = card.location_arg;
this.playCardOnTable(player_id, color, value, card.id);
}
</pre>

This should show hand and tableau cards now, except we are missing the '''playCardOnTable''' function. So find the '''getCardUniqueId''' function which
should be in the utilities section and add this after it:

<pre>
playCardOnTable : function(player_id, color, value, card_id) {
// player_id => direction
this.addTableCard(value, color, player_id, player_id);

if (player_id != this.player_id) {
// Some opponent played a card
// Move card from player panel
this.placeOnObject('cardontable_' + player_id, 'overall_player_board_' + player_id);
} else {
// You played a card. If it exists in your hand, move card from there and remove
// corresponding item

if ($('myhand_item_' + card_id)) {
this.placeOnObject('cardontable_' + player_id, 'myhand_item_' + card_id);
this.playerHand.removeFromStockById(card_id);
}
}

// In any case: move it to its final destination
this.slideToObject('cardontable_' + player_id, 'playertablecard_' + player_id).play();
},
</pre>

For this to work we also need to define the addTableCard
<pre>
addTableCard(value, color, card_player_id, playerTableId) {
const x = value - 2;
const y = color - 1;
document.getElementById('playertablecard_' + playerTableId).insertAdjacentHTML('beforeend', `
<div class="card cardontable" id="cardontable_${card_player_id}" style="background-position:-${x}00% -${y}00%"></div>
`);
},
</pre>

What this does is basically create another card object, because if it is not our card it's not in our hand (Stock) so
we have to create it out of thin air. Now we have an object with an id of 'cardontable_' + player_id. Depending
on who is playing it we either place it on the player miniboard or in hand (and remove it from hand stock). Then we animate the card move.

We also should fix our .css file now to add style for cardontable and REMOVE background for playertablecard which really is a placeholder div and not a card. (Don't miss the remove step; it will be all screwy if you do!)

<pre>
.playertablecard {
display: inline-block;
position: relative;
margin-top: 5px;
width: 72px;
height: 96px;
/* we remove background-image here */
}

/*** cards on table ***/

.cardontable {
position: absolute;
width: 72px;
height: 96px;
background-image: url('img/cards.jpg');
}
</pre>

Now to test that it actually works let's deal cards to players during game initialization:

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 ) {
$cards = $this->cards->pickCards(13, 'deck', $player_id);
}
</pre>

Now when you start the game you should see 13 cards in your hand!

We just need to hook-up clicking on card and test if our playCardOnTable works.

Find onPlayerHandSelectionChanged function in the JS file, we should have logging there like console.log("on playCard "+card_id);
So after that insert this (Note: this code is for testing we will replace it with server interaction after we test it.):
<pre>
console.log("on playCard "+card_id);
// type is (color - 1) * 13 + (value - 2)
var type = items[0].type;
var color = Math.floor(type / 13) + 1;
var value = type % 13 + 2;

this.playCardOnTable(this.player_id,color,value,card_id);
</pre>
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]]

Code Rev [https://github.com/elaskavaia/bga-heartsla/tree/0ed80e254a6d0c29f267b308d1c2016db90fd4f6]

== State Machine ==

Now we need to create a game state machine. So the states are (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 is selected who will start a new trick ("newTrick")
* 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) ("nextHand")

The state handling spread across multiple files, so you have to make sure all pieces are connected together.
The state machine states.php defines all the states, and function handlers on php side in a form of string,
and if any of these functions are not implemented it would be very hard to debug because it will break in random places.

So .states.php (remove all template states and replace with these)

<pre>
$machinestates = array(
/// New hand
2 => array(
"name" => "newHand",
"description" => "",
"type" => "game",
"action" => "stNewHand",
"updateGameProgression" => true,
"transitions" => array( "" => 30 )
),

21 => array(
"name" => "giveCards",
"description" => clienttranslate('Some players must choose 3 cards to give to ${direction}'),
"descriptionmyturn" => clienttranslate('${you} must choose 3 cards to give to ${direction}'),
"type" => "multipleactiveplayer",
"action" => "stGiveCards",
"args" => "argGiveCards",
"possibleactions" => array( "actGiveCards" ),
"transitions" => array( "giveCards" => 22, "skip" => 22 )
),

22 => array(
"name" => "takeCards",
"description" => "",
"type" => "game",
"action" => "stTakeCards",
"transitions" => array( "startHand" => 30, "skip" => 30 )
),

// Trick

30 => array(
"name" => "newTrick",
"description" => "",
"type" => "game",
"action" => "stNewTrick",
"transitions" => array( "" => 31 )
),
31 => array(
"name" => "playerTurn",
"description" => clienttranslate('${actplayer} must play a card'),
"descriptionmyturn" => clienttranslate('${you} must play a card'),
"type" => "activeplayer",
"possibleactions" => array( "actPlayCard" ),
"transitions" => array( "playCard" => 32 )
),
32 => array(
"name" => "nextPlayer",
"description" => "",
"type" => "game",
"action" => "stNextPlayer",
"transitions" => array( "nextPlayer" => 31, "nextTrick" => 30, "endHand" => 40 )
),

// End of the hand (scoring, etc...)
40 => array(
"name" => "endHand",
"description" => "",
"type" => "game",
"action" => "stEndHand",
"transitions" => array( "nextHand" => 2, "endGame" => 99 )
),

);
</pre>

The full details on these fields are in [[Your_game_state_machine:_states.inc.php]].

But basically we have Player states, in which a human player has to perform an "action" by pressing some button in the UI or selecting some game item, which will trigger js handler, which will do an ajax call to the server.

To make it run we have to define all the handler functions that we referenced in states, which are - one function for state arguments argGiveCards, 4 functions for robot states (where the game performs some action)
and 1 function for player actions handling.
In Game.php, find 'Game state arguments' section and paste this in:
<pre>
function argGiveCards() {
return [];
}
</pre>

This normally passes some parameters to states, but we don't need anything yet. It's good to have a placeholder there anyway, so we can fix it later.
Important: even when it's a stub, this function must return an array not a scalar.

Let's do stubs for other functions, find the game state actions section in Game.php file and insert these (replace all st* method defined in template)
<pre>
function stNewHand() {
// Take back all cards (from any location => null) to deck
$this->cards->moveAllCardsInLocation(null, "deck");
$this->cards->shuffle('deck');
// Deal 13 cards to each players
// Create deck, shuffle it and give 13 initial cards
$players = $this->loadPlayersBasicInfos();
foreach ( $players as $player_id => $player ) {
$cards = $this->cards->pickCards(13, 'deck', $player_id);
// Notify player about his cards
$this->notify->player($player_id, 'newHand', '', array ('cards' => $cards ));
}
$this->setGameStateValue('alreadyPlayedHearts', 0);
$this->gamestate->nextState("");
}

function stNewTrick() {
// New trick: active the player who wins the last trick, or the player who own the club-2 card
// Reset trick color to 0 (= no color)
$this->setGameStateInitialValue('trickColor', 0);
$this->gamestate->nextState();
}

function stNextPlayer() {
// Active next player OR end the trick and go to the next trick OR end the hand
if ($this->cards->countCardInLocation('cardsontable') == 4) {
// This is the end of the trick
// Move all cards to "cardswon" of the given player
$best_value_player_id = $this->activeNextPlayer(); // TODO figure out winner of trick
$this->cards->moveAllCardsInLocation('cardsontable', 'cardswon', null, $best_value_player_id);

if ($this->cards->countCardInLocation('hand') == 0) {
// End of the hand
$this->gamestate->nextState("endHand");
} else {
// End of the trick
$this->gamestate->nextState("nextTrick");
}
} else {
// Standard case (not the end of the trick)
// => just active the next player
$player_id = $this->activeNextPlayer();
$this->giveExtraTime($player_id);
$this->gamestate->nextState('nextPlayer');
}
}

function stEndHand() {
$this->gamestate->nextState("nextHand");
}

</pre>
Important: All state actions game or player must end with state transition (or thrown exception). Also make sure it's ONLY one state transition,
if you accidentally fall through after state transition and do another one it will be a real mess and head scratching for long time.

Now find 'player actions' section and paste this code there (replace all existing act* functions)
<pre>
function actPlayCard(int $card_id) {
$player_id = $this->getActivePlayerId();
throw new \BgaUserException(clienttranslate('Not implemented: ${player_id} plays ${card_id}'), [
"player_id" => "$player_id",
"card_id" => $card_id,
]);

}
</pre>
We won't implement it yet but throw an exception which we will see if interaction is working properly

If your game is running you have to exit it. When we change state machine in the middle of the game usually it won't be good.

Now the game should start but it would not be any different than before because we have to implement actual interactions.
It's good to check if it's still working though (and if it was running before you have to exit because we changed state machine and normally it will break stuff).

NOTE: When you play a card, you will not yet get the "Not implemented" message. That is added in the next section.

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
<pre>
onUpdateActionButtons: function (stateName, args) {
console.log("onUpdateActionButtons: " + stateName, args);

if (this.isCurrentPlayerActive()) {
switch (stateName) {
case "playerTurn":
break;
}
}
},
</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.

Eventhough we can it ajax call the API now called "bgaPerformAction" and this is what you should be using.

So in .js code replace onPlayerHandSelectionChanged with
<pre>
onPlayerHandSelectionChanged : function() {
var items = this.playerHand.getSelectedItems();

if (items.length > 0) {
var action = 'actPlayCard';
if (this.checkAction(action, true)) {
// Can play a card
var card_id = items[0].id;
this.bgaPerformAction(action, {
card_id : card_id,
});

this.playerHand.unselectAll();
} else if (this.checkAction('actGiveCards')) {
// Can give cards => let the player select some cards
} else {
this.playerHand.unselectAll();
}
}
},
</pre>

Now when you click on card you should get a server response: Not implemented...

Lets implement it, in Game.php
<pre>

function actPlayCard(int $card_id) {
$player_id = $this->getActivePlayerId();
$this->cards->moveCard($card_id, 'cardsontable', $player_id);
// XXX check rules here
$currentCard = $this->cards->getCard($card_id);
// And notify
$this->notify->all('playCard', clienttranslate('${player_name} plays ${value_displayed} ${color_displayed}'), array (
'i18n' => array ('color_displayed','value_displayed' ),'card_id' => $card_id,'player_id' => $player_id,
'player_name' => $this->getActivePlayerName(),
'value' => $currentCard ['type_arg'],
'value_displayed' => self::$CARD_TYPES [$currentCard ['type_arg']] ['name'],
'color' => $currentCard ['type'],
'color_displayed' => self::$CARD_SUITS [$currentCard ['type']] ['name'] ));
// Next player
$this->gamestate->nextState('playCard');
}

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

<pre>
setupNotifications : function() {
console.log('notifications subscriptions setup');
// table of notif type to delay in milliseconds
const notifs = [
['newHand', 1],
['playCard', 100],
];

notifs.forEach((notif) => {
dojo.subscribe(notif[0], this, `notif_${notif[0]}`);
this.notifqueue.setSynchronous(notif[0], notif[1]);
});

},

notif_newHand : function(notif) {
// We received a new full hand of 13 cards.
this.playerHand.removeAll();

for ( var i in notif.args.cards) {
var card = notif.args.cards[i];
var color = card.type;
var value = card.type_arg;
this.playerHand.addToStockWithId(this.getCardUniqueId(color, value), card.id);
}
},

notif_playCard : function(notif) {
// Play a card on the table
this.playCardOnTable(notif.args.player_id, notif.args.color, notif.args.value, notif.args.card_id);
},
</pre>

Now it actually works through the server when you click on card - the move is recorded. If you test it now 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 we need to send notification about it
and have a handler for it

So in Game.php file add notification in stNextPlayer function after moveAllCardsInLocation call:

<pre>
// Notify
// 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 = $this->loadPlayersBasicInfos();
$this->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']
) );
$this->notify->all( 'giveAllCardsToPlayer','', array(
'player_id' => $best_value_player_id
) );
</pre>

And in .js file add 2 more notification handlers.

This is to subscribe in setupNotifications function
<pre>
const notifs = [
...
['trickWin', 1000],
['giveAllCardsToPlayer', 600],
];
</pre>

And these are handlers
<pre>
notif_trickWin : function(notif) {
// We do nothing here (just wait in order players can view the 4 cards played before they're gone.
},
notif_giveAllCardsToPlayer : function(notif) {
// Move all cards on table to given table, then destroy them
var winner_id = notif.args.player_id;
for ( var player_id in this.gamedatas.players) {
var anim = this.slideToObject('cardontable_' + player_id, 'overall_player_board_' + winner_id);
dojo.connect(anim, 'onEnd', function(node) {
dojo.destroy(node);
});
anim.play();
}
},
</pre>

So 'trickWin' notification does not do much except it will delay the processing of next notification by 1 second (1000 ms)
and it will log the message (that happens independently of what handler does).
<i>Note: if on the other hand you don't want to log but want to do something else, send an empty message</i>

Now after the trick you see all cards move towards the "player's stash".

== 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 'trickColor' which we already conveniently created.

In Game.php file find the actPlayCard function and add this before notify functions
$currentTrickColor = $this->getGameStateValue( 'trickColor' ) ;
if( $currentTrickColor == 0 )
$this->setGameStateValue( 'trickColor', $currentCard['type'] );

This will make sure we remember the first suit being played, now to use it modify the stNextPlayer function to fix our TODO comment
<pre>
function stNextPlayer() {
// Active next player OR end the trick and go to the next trick OR end the hand
if ($this->cards->countCardInLocation('cardsontable') == 4) {
// This is the end of the trick
$cards_on_table = $this->cards->getCardsInLocation('cardsontable');
$best_value = 0;
$best_value_player_id = null;
$currentTrickColor = $this->getGameStateValue('trickColor');
foreach ( $cards_on_table as $card ) {
// Note: type = card color
if ($card ['type'] == $currentTrickColor) {
if ($best_value_player_id === null || $card ['type_arg'] > $best_value) {
$best_value_player_id = $card ['location_arg']; // Note: location_arg = player who played this card on table
$best_value = $card ['type_arg']; // Note: type_arg = value of the card
}
}
}

// Active this player => he's the one who starts the next trick
$this->gamestate->changeActivePlayer( $best_value_player_id );

// Move all cards to "cardswon" of the given player
$this->cards->moveAllCardsInLocation('cardsontable', 'cardswon', null, $best_value_player_id);

// Notify
// ... same code here 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, also
we want to show that in the log.
In addition scoring can be shown in [[Game_interface_logic:_yourgamename.js#Scoring_dialogs|Scoring Dialog]] using tableWindow notification, but it is a tutorial on its own and you can do it as homework (it is part of original heart game).

so in Game.php our stEndHand function will look like

<pre>
function stEndHand() {
// Count and score points, then end the game or go to the next hand.
$players = $this->loadPlayersBasicInfos();
// Gets all "hearts" + queen of spades

$player_to_points = array ();
foreach ( $players as $player_id => $player ) {
$player_to_points [$player_id] = 0;
}
$cards = $this->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) {
$this->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 ($this->playerScore->getMin() <= -100) {
// Trigger the end of the game !
$this->gamestate->nextState("endGame");
return;
}

$this->gamestate->nextState("nextHand");
}
</pre>

So it should more less work now, including end of game condition. Try to play it!

== Additional stuff ==

The following things were not implemented and can add them yourself by looking at the code of original hearts game:

* Remove debug code from setupNewGame to deal cards, cards are now dealt in stNewHand state handler
* Rule checking and rule enforcements in actPlayCard function
* Start scoring with 100 points each and end when <= 0
* Fix scoring rules with Q of spades and 26 point reverse scoring
* First player one with 2 club
* Add progress handling
* 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

2025-10-04T23:43:11Z

ShaharHarshuv: Undo revision 26738 by ShaharHarshuv (talk)

{{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]]).
* Know the rules for Hearts
* 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]

== 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. 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.
</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 full game can be found in your FTP home folder, after getting read-only access: https://en.doc.boardgamearena.com/First_steps_with_BGA_Studio#Set_up_dev_environment_ide,_editor_and_File_Sync

== 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://github.com/elaskavaia/bga-heartsla/blob/4b3a73eeb5acae961ade18473af119e8ce8d1a8f/img/cards.jpg hearts img/cards.jpg] into img/ folder of your project.
<blockquote>There are better quality deck of cards image at https://en.doc.boardgamearena.com/Common_board_game_elements_image_resources</blockquote>

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>
document.getElementById('game_play_area').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 (the image slightly obsolete, you may see more stuff there and different prompt).

[[File:Heartsla-tpl2.png]]

Now lets add a card into the hand, just so you can feel it. Edit the html string we inserted earlier and a playertablecard div inside a hand div
<pre>
...
<div id="myhand">
<div class="playertablecard"></div>
</div>
...
</pre>

Edit .css file
<pre>
.playertablecard {
display: inline-block;
position: relative;
margin-top: 5px;
width: 72px;
height: 96px;
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:

[[File:Heartsla-tpl3.png]]

Awesome! Now lets do the rest of layout.

Note: If you don't see the card a) check it was synced to remote folder b) force reload page

Let's complete the template string we created for the hand. You template should have this code, just leave it there
<pre>

// Example to add a div on the game area
document.getElementById("game_play_area").insertAdjacentHTML("beforeend",
`
<div id="player-tables"></div>
`
);
</pre>

Then change the following template code to this
<pre>
// Setting up player boards
var numPlayers = Object.keys(gamedatas.players).length;
Object.values(gamedatas.players).forEach((player, index) => {
document.getElementById("player-tables").insertAdjacentHTML(
"beforeend",
`
<div class="playertable whiteblock playertable_${DIRECTIONS[numPlayers][index]}">
<div class="playertablename" style="color:#${player.color};"><span class="dealer_token" id="dealer_token_p${player.id}">🃏 </span>${player.name}</div>
<div class="playertablecard" id="playertablecard_${player.id}"></div>
<div class="playertablename" id="hand_score_wrap_${player.id}"><span class="hand_score_label"></span> <span id="hand_score_${player.id}"></span></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
heartslav.js:68 Uncaught (in promise) ReferenceError: DIRECTIONS is not defined

For this new code to work, we need to add a constant at the beginning of the JS file, defining the expected position of each player (right after copyright comment):
<pre>
const DIRECTIONS = {
3: ['S', 'W', 'E'],
4: ['S', 'W', 'N', 'E'],
};
</pre>

Reload. If everything went well you should see this:

[[File:Hearts all rows.png|alt=Display a list of all players, with a dummy card in each position]]

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>
/** Table layout **/

#player-tables {
position: relative;
width: 710px;
height: 340px;
}

.playertablename {
font-weight: bold;
}

.playertable {
position: absolute;
text-align: center;
width: 180px;
height: 130px;
}

.playertable_N {
left: 50%;
top: 0px;
margin-left: -90px; /* half of 180 */
}
.playertable_S {
left: 50%;
bottom: 0px;
margin-left: -90px; /* half of 180 */
}
.playertable_W {
left: 0px;
top: 50%;
margin-top: -55px; /* half of 130 */
}
.playertable_E {
right: 0px;
top: 50%;
margin-top: -55px; /* half of 130 */
}
</pre>

Now you force Reload and you should see this:
[[File:Heartsla-tpl5.png]]

This is almost all we need for graphics and layout, there are few tweaks left there but lets do some more heavy lifting now.

<i>Note: if you did not see changes you may have not force reloaded, force means you use Ctrl+F5 or Cltr+Shift-R, if you don't "force" browser will use cached version of images! Which is not what you just changed</i>

<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 JS Stock ==

The BGA framework provides a few out of the box classes to deal with cards. The client side
contains a class called [[Stock]] and it can be used for any dynamic html "pieces" management that uses
common sprite images. 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 13x4 grid of images stitched together,
which is a very efficient way to transport images. So we will use the Stock class to mark up these images and create
"card" divs for us.

First, we need to add '''ebg/stock''' as a dependency in the .js file:
<pre>
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/stock" /// <==== HERE, don't forget comma before
],
</pre>

Then add this to the Javascript constructor, this will define size of our cards
<pre>
console.log('hearts constructor');
this.cardwidth = 72;
this.cardheight = 96;
</pre>

The stock is initialized in the Javascript "setup" method like this:
<pre>
// TODO: Set up your game interface here, according to "gamedatas"

// Player hand
this.playerHand = new ebg.stock(); // new stock object for hand
this.playerHand.create( this, $('myhand'), this.cardwidth, this.cardheight );
</pre>

As parameters of the "create" method, we provided the width/height of an item (a card), and the container div "myhand" - which is an id of "div" element from our .tpl file representing a player hand.

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

Here's how we tell stock what item types to display (add after .create):
<pre>
this.playerHand.image_items_per_row = 13; // 13 images per row

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

And add this function to the utilities section
<pre>
// Get card unique identifier based on its color and value
getCardUniqueId : function(color, value) {
return (color - 1) * 13 + (value - 2);
},
</pre>

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

Note: we need to generate a unique ID for each type of card based on its color and value. For that we create a function '''getCardUniqueId'''. The type is the unique identifier of the TYPE of the card, e.g., the queen of spades encoded as an integer. If our deck had 2 standard card decks we would have had 2 queens of spades; they would share the same type and the same image but would have different ids. NOTE: It's unfortunate that they named this '''getCardUniqueId'''; it should have been '''getCardUniqueType''', because it really isn't an id, but a TYPE of card. The type of the item should either be a reversible function of its properties (i.e., kind of suite * 13 + value) or just an enumerator described in material.inc.php. In this specific case it's a synthetic type id, which also the same as the number of the card in the sprite image (i.e., if you enumerate each image in sprite going left to right, then top to bottom).

Now let's add the 5 of Hearts to the player's hand just for fun (this code will go in setup method after types initialization):

<pre>
// 2 = hearts, 5 is 5, and 42 is the card id, which normally would come from db
this.playerHand.addToStockWithId( this.getCardUniqueId( 2, 5 ), 42 );
</pre>

This will add the card with id 42 and type 16 ( (2-1)*13+(5-2)=16 ).

Note that number 16 would not be something you can see in database, Deck database will have separate field for type and type_arg where type is suite and type_arg is number, so its not the same thing, but you can use same formula to convert. Number 42 on the other hand would be id field in database. But we get to database in the later section.

If you reload now you should see the 5 of hearts in "your hand".

You may see some weird graphics glitches - its because we did not remove our hack with background from .css yet. You can go to .css file now and remove line with comment "temp hack to see it".

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, after this.playerHand is initialised:

dojo.connect( this.playerHand, 'onChangeSelection', this, 'onPlayerHandSelectionChanged' );

Then find the Player's action comment section in .js file and add a handler after the comment:

<pre>
///////////////////////////////////////////////////
//// Player's action

onPlayerHandSelectionChanged: function () {
var items = this.playerHand.getSelectedItems();

if (items.length > 0) {
if (this.checkAction("actPlayCard", true)) {
// Can play a card

var card_id = items[0].id;
console.log("on playCard " + card_id);

this.playerHand.unselectAll();
} else if (this.checkAction("actGiveCards")) {
// Can give cards => let the player select some cards
} else {
this.playerHand.unselectAll();
}
}
},
</pre>

''Note : If you already have an example handler <code>onCardClick: function( card_id )</code>, go ahead and remove that handler, it is a duplicate of what we are implementing in this tutorial and may cause issues later on.''

The function name of the handler is 4th parameter of the dojo.connect function. Make sure you spell it correctly or there will be unpredictable effects.

Now if you reload, open the Javascript Console (F12), and then click on the card in My Hand, you should see:
on playCard 42
printed on the console

''Note : You need to be the active player to have rights to play a card and so log your message in the console''

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

To modify the schema, first exit your existing game(s). Open '''dbmodel.sql''' file and uncomment the card table creation.

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

This is the "card" table which will be managed by the Deck php class.

In addition we want a little piece of information in the players table:

-- add info about first player
ALTER TABLE `player` ADD `player_first` BOOLEAN NOT NULL DEFAULT '0';

Not sure why they put this into the player table, as we could use a global db variable to hold first player as easily.
But I am just following the existing code more-or-less. It is not recommended to modify player table in general.

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>
parent::__construct();
$this->initGameStateLabels( array(
"currentHandType" => 10,
"trickColor" => 11,
"alreadyPlayedHearts" => 12,
) );

$this->cards = $this->deckFactory->createDeck('card');
</pre>

If you see errors in IDE its because we also have to declared "cards" as class member, add protected $cards; before the contructor.

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:

* "trickColor": numbers from 1 to 4 that map to card suit (not sure why it's called color; maybe it's a translation from French);
* "alreadyPlayedHearts": a boolean flag (0 or 1) indicating whether somebody used hearts on the trick;
* "currentHandType": stores the value to indicate who to give cards to during exchange.

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->init( "foo" )</i>

Note: lower in the code there is a line that needs to be removed in order for the game to start. Search for it and remove it now.
$this->setGameStateInitialValue("my_first_global_variable", 0);

Since we changed the db, 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>

Code Rev [https://github.com/elaskavaia/bga-heartsla/tree/acd1926a6c09dc9afd0752cb6b78eef17c5dfe5c]

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 "Start the game initialization" comment.
<pre>
// Init global values with their initial values

// Note: hand types: 0 = give 3 cards to player on the left
// 1 = give 3 cards to player on the right
// 2 = give 3 cards to player opposite
// 3 = keep cards
$this->setGameStateInitialValue( 'currentHandType', 0 );

// Set current trick color to zero (= no trick color)
$this->setGameStateInitialValue( 'trickColor', 0 );

// Mark if we already played hearts during this hand
$this->setGameStateInitialValue( 'alreadyPlayedHearts', 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.
<pre>
// Create cards
$cards = [];
foreach (self::$CARD_SUITS as $suit => $suit_info) {
// spade, heart, diamond, club
foreach (self::$CARD_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 $this->colors.
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

<pre>
self::$CARD_SUITS = [
1 => [
'name' => clienttranslate('Spade'),
],
2 => [
'name' => clienttranslate('Heart'),
],
3 => [
'name' => clienttranslate('Club'),
],
4 => [
'name' => clienttranslate('Diamond'),
]
];

self::$CARD_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 declared these fields in the class
private static array $CARD_SUITS;
private static array $CARD_TYPES;

== Full game model synchronisation ==

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. 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', $current_player_id );

// 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 .js file in the setup function (which is the receiver of getAllDatas) replace our hack of putting 5 of Hearts directly into the hand with:

<pre>
// Cards in player's hand
for ( var i in this.gamedatas.hand) {
var card = this.gamedatas.hand[i];
var color = card.type;
var value = card.type_arg;
this.playerHand.addToStockWithId(this.getCardUniqueId(color, value), card.id);
}

// Cards played on table
for (i in this.gamedatas.cardsontable) {
var card = this.gamedatas.cardsontable[i];
var color = card.type;
var value = card.type_arg;
var player_id = card.location_arg;
this.playCardOnTable(player_id, color, value, card.id);
}
</pre>

This should show hand and tableau cards now, except we are missing the '''playCardOnTable''' function. So find the '''getCardUniqueId''' function which
should be in the utilities section and add this after it:

<pre>
playCardOnTable : function(player_id, color, value, card_id) {
// player_id => direction
this.addTableCard(value, color, player_id, player_id);

if (player_id != this.player_id) {
// Some opponent played a card
// Move card from player panel
this.placeOnObject('cardontable_' + player_id, 'overall_player_board_' + player_id);
} else {
// You played a card. If it exists in your hand, move card from there and remove
// corresponding item

if ($('myhand_item_' + card_id)) {
this.placeOnObject('cardontable_' + player_id, 'myhand_item_' + card_id);
this.playerHand.removeFromStockById(card_id);
}
}

// In any case: move it to its final destination
this.slideToObject('cardontable_' + player_id, 'playertablecard_' + player_id).play();
},
</pre>

For this to work we also need to define the addTableCard
<pre>
addTableCard(value, color, card_player_id, playerTableId) {
const x = value - 2;
const y = color - 1;
document.getElementById('playertablecard_' + playerTableId).insertAdjacentHTML('beforeend', `
<div class="card cardontable" id="cardontable_${card_player_id}" style="background-position:-${x}00% -${y}00%"></div>
`);
},
</pre>

What this does is basically create another card object, because if it is not our card it's not in our hand (Stock) so
we have to create it out of thin air. Now we have an object with an id of 'cardontable_' + player_id. Depending
on who is playing it we either place it on the player miniboard or in hand (and remove it from hand stock). Then we animate the card move.

We also should fix our .css file now to add style for cardontable and REMOVE background for playertablecard which really is a placeholder div and not a card. (Don't miss the remove step; it will be all screwy if you do!)

<pre>
.playertablecard {
display: inline-block;
position: relative;
margin-top: 5px;
width: 72px;
height: 96px;
/* we remove background-image here */
}

/*** cards on table ***/

.cardontable {
position: absolute;
width: 72px;
height: 96px;
background-image: url('img/cards.jpg');
}
</pre>

Now to test that it actually works let's deal cards to players during game initialization:

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 ) {
$cards = $this->cards->pickCards(13, 'deck', $player_id);
}
</pre>

Now when you start the game you should see 13 cards in your hand!

We just need to hook-up clicking on card and test if our playCardOnTable works.

Find onPlayerHandSelectionChanged function in the JS file, we should have logging there like console.log("on playCard "+card_id);
So after that insert this (Note: this code is for testing we will replace it with server interaction after we test it.):
<pre>
console.log("on playCard "+card_id);
// type is (color - 1) * 13 + (value - 2)
var type = items[0].type;
var color = Math.floor(type / 13) + 1;
var value = type % 13 + 2;

this.playCardOnTable(this.player_id,color,value,card_id);
</pre>
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]]

Code Rev [https://github.com/elaskavaia/bga-heartsla/tree/0ed80e254a6d0c29f267b308d1c2016db90fd4f6]

== State Machine ==

Now we need to create a game state machine. So the states are (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 is selected who will start a new trick ("newTrick")
* 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) ("nextHand")

The state handling spread across multiple files, so you have to make sure all pieces are connected together.
The state machine states.php defines all the states, and function handlers on php side in a form of string,
and if any of these functions are not implemented it would be very hard to debug because it will break in random places.

So .states.php (remove all template states and replace with these)

<pre>
$machinestates = array(
/// New hand
2 => array(
"name" => "newHand",
"description" => "",
"type" => "game",
"action" => "stNewHand",
"updateGameProgression" => true,
"transitions" => array( "" => 30 )
),

21 => array(
"name" => "giveCards",
"description" => clienttranslate('Some players must choose 3 cards to give to ${direction}'),
"descriptionmyturn" => clienttranslate('${you} must choose 3 cards to give to ${direction}'),
"type" => "multipleactiveplayer",
"action" => "stGiveCards",
"args" => "argGiveCards",
"possibleactions" => array( "actGiveCards" ),
"transitions" => array( "giveCards" => 22, "skip" => 22 )
),

22 => array(
"name" => "takeCards",
"description" => "",
"type" => "game",
"action" => "stTakeCards",
"transitions" => array( "startHand" => 30, "skip" => 30 )
),

// Trick

30 => array(
"name" => "newTrick",
"description" => "",
"type" => "game",
"action" => "stNewTrick",
"transitions" => array( "" => 31 )
),
31 => array(
"name" => "playerTurn",
"description" => clienttranslate('${actplayer} must play a card'),
"descriptionmyturn" => clienttranslate('${you} must play a card'),
"type" => "activeplayer",
"possibleactions" => array( "actPlayCard" ),
"transitions" => array( "playCard" => 32 )
),
32 => array(
"name" => "nextPlayer",
"description" => "",
"type" => "game",
"action" => "stNextPlayer",
"transitions" => array( "nextPlayer" => 31, "nextTrick" => 30, "endHand" => 40 )
),

// End of the hand (scoring, etc...)
40 => array(
"name" => "endHand",
"description" => "",
"type" => "game",
"action" => "stEndHand",
"transitions" => array( "nextHand" => 2, "endGame" => 99 )
),

);
</pre>

The full details on these fields are in [[Your_game_state_machine:_states.inc.php]].

But basically we have Player states, in which a human player has to perform an "action" by pressing some button in the UI or selecting some game item, which will trigger js handler, which will do an ajax call to the server.

To make it run we have to define all the handler functions that we referenced in states, which are - one function for state arguments argGiveCards, 4 functions for robot states (where the game performs some action)
and 1 function for player actions handling.
In Game.php, find 'Game state arguments' section and paste this in:
<pre>
function argGiveCards() {
return [];
}
</pre>

This normally passes some parameters to states, but we don't need anything yet. It's good to have a placeholder there anyway, so we can fix it later.
Important: even when it's a stub, this function must return an array not a scalar.

Let's do stubs for other functions, find the game state actions section in Game.php file and insert these (replace all st* method defined in template)
<pre>
function stNewHand() {
// Take back all cards (from any location => null) to deck
$this->cards->moveAllCardsInLocation(null, "deck");
$this->cards->shuffle('deck');
// Deal 13 cards to each players
// Create deck, shuffle it and give 13 initial cards
$players = $this->loadPlayersBasicInfos();
foreach ( $players as $player_id => $player ) {
$cards = $this->cards->pickCards(13, 'deck', $player_id);
// Notify player about his cards
$this->notify->player($player_id, 'newHand', '', array ('cards' => $cards ));
}
$this->setGameStateValue('alreadyPlayedHearts', 0);
$this->gamestate->nextState("");
}

function stNewTrick() {
// New trick: active the player who wins the last trick, or the player who own the club-2 card
// Reset trick color to 0 (= no color)
$this->setGameStateInitialValue('trickColor', 0);
$this->gamestate->nextState();
}

function stNextPlayer() {
// Active next player OR end the trick and go to the next trick OR end the hand
if ($this->cards->countCardInLocation('cardsontable') == 4) {
// This is the end of the trick
// Move all cards to "cardswon" of the given player
$best_value_player_id = $this->activeNextPlayer(); // TODO figure out winner of trick
$this->cards->moveAllCardsInLocation('cardsontable', 'cardswon', null, $best_value_player_id);

if ($this->cards->countCardInLocation('hand') == 0) {
// End of the hand
$this->gamestate->nextState("endHand");
} else {
// End of the trick
$this->gamestate->nextState("nextTrick");
}
} else {
// Standard case (not the end of the trick)
// => just active the next player
$player_id = $this->activeNextPlayer();
$this->giveExtraTime($player_id);
$this->gamestate->nextState('nextPlayer');
}
}

function stEndHand() {
$this->gamestate->nextState("nextHand");
}

</pre>
Important: All state actions game or player must end with state transition (or thrown exception). Also make sure it's ONLY one state transition,
if you accidentally fall through after state transition and do another one it will be a real mess and head scratching for long time.

Now find 'player actions' section and paste this code there (replace all existing act* functions)
<pre>
function actPlayCard(int $card_id) {
$player_id = $this->getActivePlayerId();
throw new \BgaUserException(clienttranslate('Not implemented: ${player_id} plays ${card_id}'), [
"player_id" => "$player_id",
"card_id" => $card_id,
]);

}
</pre>
We won't implement it yet but throw an exception which we will see if interaction is working properly

If your game is running you have to exit it. When we change state machine in the middle of the game usually it won't be good.

Now the game should start but it would not be any different than before because we have to implement actual interactions.
It's good to check if it's still working though (and if it was running before you have to exit because we changed state machine and normally it will break stuff).

NOTE: When you play a card, you will not yet get the "Not implemented" message. That is added in the next section.

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
<pre>
onUpdateActionButtons: function (stateName, args) {
console.log("onUpdateActionButtons: " + stateName, args);

if (this.isCurrentPlayerActive()) {
switch (stateName) {
case "playerTurn":
break;
}
}
},
</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.

Eventhough we can it ajax call the API now called "bgaPerformAction" and this is what you should be using.

So in .js code replace onPlayerHandSelectionChanged with
<pre>
onPlayerHandSelectionChanged : function() {
var items = this.playerHand.getSelectedItems();

if (items.length > 0) {
var action = 'actPlayCard';
if (this.checkAction(action, true)) {
// Can play a card
var card_id = items[0].id;
this.bgaPerformAction(action, {
card_id : card_id,
});

this.playerHand.unselectAll();
} else if (this.checkAction('actGiveCards')) {
// Can give cards => let the player select some cards
} else {
this.playerHand.unselectAll();
}
}
},
</pre>

Now when you click on card you should get a server response: Not implemented...

Lets implement it, in Game.php
<pre>

function actPlayCard(int $card_id) {
$player_id = $this->getActivePlayerId();
$this->cards->moveCard($card_id, 'cardsontable', $player_id);
// XXX check rules here
$currentCard = $this->cards->getCard($card_id);
// And notify
$this->notify->all('playCard', clienttranslate('${player_name} plays ${value_displayed} ${color_displayed}'), array (
'i18n' => array ('color_displayed','value_displayed' ),'card_id' => $card_id,'player_id' => $player_id,
'player_name' => $this->getActivePlayerName(),
'value' => $currentCard ['type_arg'],
'value_displayed' => self::$CARD_TYPES [$currentCard ['type_arg']] ['name'],
'color' => $currentCard ['type'],
'color_displayed' => self::$CARD_SUITS [$currentCard ['type']] ['name'] ));
// Next player
$this->gamestate->nextState('playCard');
}

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

<pre>
setupNotifications : function() {
console.log('notifications subscriptions setup');
// table of notif type to delay in milliseconds
const notifs = [
['newHand', 1],
['playCard', 100],
];

notifs.forEach((notif) => {
dojo.subscribe(notif[0], this, `notif_${notif[0]}`);
this.notifqueue.setSynchronous(notif[0], notif[1]);
});

},

notif_newHand : function(notif) {
// We received a new full hand of 13 cards.
this.playerHand.removeAll();

for ( var i in notif.args.cards) {
var card = notif.args.cards[i];
var color = card.type;
var value = card.type_arg;
this.playerHand.addToStockWithId(this.getCardUniqueId(color, value), card.id);
}
},

notif_playCard : function(notif) {
// Play a card on the table
this.playCardOnTable(notif.args.player_id, notif.args.color, notif.args.value, notif.args.card_id);
},
</pre>

Now it actually works through the server when you click on card - the move is recorded. If you test it now 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 we need to send notification about it
and have a handler for it

So in Game.php file add notification in stNextPlayer function after moveAllCardsInLocation call:

<pre>
// Notify
// 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 = $this->loadPlayersBasicInfos();
$this->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']
) );
$this->notify->all( 'giveAllCardsToPlayer','', array(
'player_id' => $best_value_player_id
) );
</pre>

And in .js file add 2 more notification handlers.

This is to subscribe in setupNotifications function
<pre>
const notifs = [
...
['trickWin', 1000],
['giveAllCardsToPlayer', 600],
];
</pre>

And these are handlers
<pre>
notif_trickWin : function(notif) {
// We do nothing here (just wait in order players can view the 4 cards played before they're gone.
},
notif_giveAllCardsToPlayer : function(notif) {
// Move all cards on table to given table, then destroy them
var winner_id = notif.args.player_id;
for ( var player_id in this.gamedatas.players) {
var anim = this.slideToObject('cardontable_' + player_id, 'overall_player_board_' + winner_id);
dojo.connect(anim, 'onEnd', function(node) {
dojo.destroy(node);
});
anim.play();
}
},
</pre>

So 'trickWin' notification does not do much except it will delay the processing of next notification by 1 second (1000 ms)
and it will log the message (that happens independently of what handler does).
<i>Note: if on the other hand you don't want to log but want to do something else, send an empty message</i>

Now after the trick you see all cards move towards the "player's stash".

== 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 'trickColor' which we already conveniently created.

In Game.php file find the actPlayCard function and add this before notify functions
$currentTrickColor = $this->getGameStateValue( 'trickColor' ) ;
if( $currentTrickColor == 0 )
$this->setGameStateValue( 'trickColor', $currentCard['type'] );

This will make sure we remember the first suit being played, now to use it modify the stNextPlayer function to fix our TODO comment
<pre>
function stNextPlayer() {
// Active next player OR end the trick and go to the next trick OR end the hand
if ($this->cards->countCardInLocation('cardsontable') == 4) {
// This is the end of the trick
$cards_on_table = $this->cards->getCardsInLocation('cardsontable');
$best_value = 0;
$best_value_player_id = null;
$currentTrickColor = $this->getGameStateValue('trickColor');
foreach ( $cards_on_table as $card ) {
// Note: type = card color
if ($card ['type'] == $currentTrickColor) {
if ($best_value_player_id === null || $card ['type_arg'] > $best_value) {
$best_value_player_id = $card ['location_arg']; // Note: location_arg = player who played this card on table
$best_value = $card ['type_arg']; // Note: type_arg = value of the card
}
}
}

// Active this player => he's the one who starts the next trick
$this->gamestate->changeActivePlayer( $best_value_player_id );

// Move all cards to "cardswon" of the given player
$this->cards->moveAllCardsInLocation('cardsontable', 'cardswon', null, $best_value_player_id);

// Notify
// ... same code here 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, also
we want to show that in the log.
In addition scoring can be shown in [[Game_interface_logic:_yourgamename.js#Scoring_dialogs|Scoring Dialog]] using tableWindow notification, but it is a tutorial on its own and you can do it as homework (it is part of original heart game).

so in Game.php our stEndHand function will look like

<pre>
function stEndHand() {
// Count and score points, then end the game or go to the next hand.
$players = $this->loadPlayersBasicInfos();
// Gets all "hearts" + queen of spades

$player_to_points = array ();
foreach ( $players as $player_id => $player ) {
$player_to_points [$player_id] = 0;
}
$cards = $this->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) {
$this->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 ($this->playerScore->getMin() <= -100) {
// Trigger the end of the game !
$this->gamestate->nextState("endGame");
return;
}

$this->gamestate->nextState("nextHand");
}
</pre>

So it should more less work now, including end of game condition. Try to play it!

== Additional stuff ==

The following things were not implemented and can add them yourself by looking at the code of original hearts game:

* Remove debug code from setupNewGame to deal cards, cards are now dealt in stNewHand state handler
* Rule checking and rule enforcements in actPlayCard function
* Start scoring with 100 points each and end when <= 0
* Fix scoring rules with Q of spades and 26 point reverse scoring
* First player one with 2 club
* Add progress handling
* 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

2025-10-04T23:39:40Z

ShaharHarshuv:

{{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]]).
* Know the rules for Hearts
* 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]

== 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. 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.
</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 full game can be found in your FTP home folder, after getting read-only access: https://en.doc.boardgamearena.com/First_steps_with_BGA_Studio#Set_up_dev_environment_ide,_editor_and_File_Sync

== 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://github.com/elaskavaia/bga-heartsla/blob/4b3a73eeb5acae961ade18473af119e8ce8d1a8f/img/cards.jpg hearts img/cards.jpg] into img/ folder of your project.
<blockquote>There are better quality deck of cards image at https://en.doc.boardgamearena.com/Common_board_game_elements_image_resources</blockquote>

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>
document.getElementById('game_play_area').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:heartstutorial-1.png]]

Now lets add a card into the hand, just so you can feel it. Edit the html string we inserted earlier and a playertablecard div inside a hand div
<pre>
...
<div id="myhand">
<div class="playertablecard"></div>
</div>
...
</pre>

Edit .css file
<pre>
.playertablecard {
display: inline-block;
position: relative;
margin-top: 5px;
width: 72px;
height: 96px;
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:

[[File:Heartsla-tpl3.png]]

Awesome! Now lets do the rest of layout.

Note: If you don't see the card a) check it was synced to remote folder b) force reload page

Let's complete the template string we created for the hand. You template should have this code, just leave it there
<pre>

// Example to add a div on the game area
document.getElementById("game_play_area").insertAdjacentHTML("beforeend",
`
<div id="player-tables"></div>
`
);
</pre>

Then change the following template code to this
<pre>
// Setting up player boards
var numPlayers = Object.keys(gamedatas.players).length;
Object.values(gamedatas.players).forEach((player, index) => {
document.getElementById("player-tables").insertAdjacentHTML(
"beforeend",
`
<div class="playertable whiteblock playertable_${DIRECTIONS[numPlayers][index]}">
<div class="playertablename" style="color:#${player.color};"><span class="dealer_token" id="dealer_token_p${player.id}">🃏 </span>${player.name}</div>
<div class="playertablecard" id="playertablecard_${player.id}"></div>
<div class="playertablename" id="hand_score_wrap_${player.id}"><span class="hand_score_label"></span> <span id="hand_score_${player.id}"></span></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
heartslav.js:68 Uncaught (in promise) ReferenceError: DIRECTIONS is not defined

For this new code to work, we need to add a constant at the beginning of the JS file, defining the expected position of each player (right after copyright comment):
<pre>
const DIRECTIONS = {
3: ['S', 'W', 'E'],
4: ['S', 'W', 'N', 'E'],
};
</pre>

Reload. If everything went well you should see this:

[[File:Hearts all rows.png|alt=Display a list of all players, with a dummy card in each position]]

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>
/** Table layout **/

#player-tables {
position: relative;
width: 710px;
height: 340px;
}

.playertablename {
font-weight: bold;
}

.playertable {
position: absolute;
text-align: center;
width: 180px;
height: 130px;
}

.playertable_N {
left: 50%;
top: 0px;
margin-left: -90px; /* half of 180 */
}
.playertable_S {
left: 50%;
bottom: 0px;
margin-left: -90px; /* half of 180 */
}
.playertable_W {
left: 0px;
top: 50%;
margin-top: -55px; /* half of 130 */
}
.playertable_E {
right: 0px;
top: 50%;
margin-top: -55px; /* half of 130 */
}
</pre>

Now you force Reload and you should see this:
[[File:Heartsla-tpl5.png]]

This is almost all we need for graphics and layout, there are few tweaks left there but lets do some more heavy lifting now.

<i>Note: if you did not see changes you may have not force reloaded, force means you use Ctrl+F5 or Cltr+Shift-R, if you don't "force" browser will use cached version of images! Which is not what you just changed</i>

<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 JS Stock ==

The BGA framework provides a few out of the box classes to deal with cards. The client side
contains a class called [[Stock]] and it can be used for any dynamic html "pieces" management that uses
common sprite images. 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 13x4 grid of images stitched together,
which is a very efficient way to transport images. So we will use the Stock class to mark up these images and create
"card" divs for us.

First, we need to add '''ebg/stock''' as a dependency in the .js file:
<pre>
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/stock" /// <==== HERE, don't forget comma before
],
</pre>

Then add this to the Javascript constructor, this will define size of our cards
<pre>
console.log('hearts constructor');
this.cardwidth = 72;
this.cardheight = 96;
</pre>

The stock is initialized in the Javascript "setup" method like this:
<pre>
// TODO: Set up your game interface here, according to "gamedatas"

// Player hand
this.playerHand = new ebg.stock(); // new stock object for hand
this.playerHand.create( this, $('myhand'), this.cardwidth, this.cardheight );
</pre>

As parameters of the "create" method, we provided the width/height of an item (a card), and the container div "myhand" - which is an id of "div" element from our .tpl file representing a player hand.

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

Here's how we tell stock what item types to display (add after .create):
<pre>
this.playerHand.image_items_per_row = 13; // 13 images per row

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

And add this function to the utilities section
<pre>
// Get card unique identifier based on its color and value
getCardUniqueId : function(color, value) {
return (color - 1) * 13 + (value - 2);
},
</pre>

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

Note: we need to generate a unique ID for each type of card based on its color and value. For that we create a function '''getCardUniqueId'''. The type is the unique identifier of the TYPE of the card, e.g., the queen of spades encoded as an integer. If our deck had 2 standard card decks we would have had 2 queens of spades; they would share the same type and the same image but would have different ids. NOTE: It's unfortunate that they named this '''getCardUniqueId'''; it should have been '''getCardUniqueType''', because it really isn't an id, but a TYPE of card. The type of the item should either be a reversible function of its properties (i.e., kind of suite * 13 + value) or just an enumerator described in material.inc.php. In this specific case it's a synthetic type id, which also the same as the number of the card in the sprite image (i.e., if you enumerate each image in sprite going left to right, then top to bottom).

Now let's add the 5 of Hearts to the player's hand just for fun (this code will go in setup method after types initialization):

<pre>
// 2 = hearts, 5 is 5, and 42 is the card id, which normally would come from db
this.playerHand.addToStockWithId( this.getCardUniqueId( 2, 5 ), 42 );
</pre>

This will add the card with id 42 and type 16 ( (2-1)*13+(5-2)=16 ).

Note that number 16 would not be something you can see in database, Deck database will have separate field for type and type_arg where type is suite and type_arg is number, so its not the same thing, but you can use same formula to convert. Number 42 on the other hand would be id field in database. But we get to database in the later section.

If you reload now you should see the 5 of hearts in "your hand".

You may see some weird graphics glitches - its because we did not remove our hack with background from .css yet. You can go to .css file now and remove line with comment "temp hack to see it".

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, after this.playerHand is initialised:

dojo.connect( this.playerHand, 'onChangeSelection', this, 'onPlayerHandSelectionChanged' );

Then find the Player's action comment section in .js file and add a handler after the comment:

<pre>
///////////////////////////////////////////////////
//// Player's action

onPlayerHandSelectionChanged: function () {
var items = this.playerHand.getSelectedItems();

if (items.length > 0) {
if (this.checkAction("actPlayCard", true)) {
// Can play a card

var card_id = items[0].id;
console.log("on playCard " + card_id);

this.playerHand.unselectAll();
} else if (this.checkAction("actGiveCards")) {
// Can give cards => let the player select some cards
} else {
this.playerHand.unselectAll();
}
}
},
</pre>

''Note : If you already have an example handler <code>onCardClick: function( card_id )</code>, go ahead and remove that handler, it is a duplicate of what we are implementing in this tutorial and may cause issues later on.''

The function name of the handler is 4th parameter of the dojo.connect function. Make sure you spell it correctly or there will be unpredictable effects.

Now if you reload, open the Javascript Console (F12), and then click on the card in My Hand, you should see:
on playCard 42
printed on the console

''Note : You need to be the active player to have rights to play a card and so log your message in the console''

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

To modify the schema, first exit your existing game(s). Open '''dbmodel.sql''' file and uncomment the card table creation.

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

This is the "card" table which will be managed by the Deck php class.

In addition we want a little piece of information in the players table:

-- add info about first player
ALTER TABLE `player` ADD `player_first` BOOLEAN NOT NULL DEFAULT '0';

Not sure why they put this into the player table, as we could use a global db variable to hold first player as easily.
But I am just following the existing code more-or-less. It is not recommended to modify player table in general.

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>
parent::__construct();
$this->initGameStateLabels( array(
"currentHandType" => 10,
"trickColor" => 11,
"alreadyPlayedHearts" => 12,
) );

$this->cards = $this->deckFactory->createDeck('card');
</pre>

If you see errors in IDE its because we also have to declared "cards" as class member, add protected $cards; before the contructor.

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:

* "trickColor": numbers from 1 to 4 that map to card suit (not sure why it's called color; maybe it's a translation from French);
* "alreadyPlayedHearts": a boolean flag (0 or 1) indicating whether somebody used hearts on the trick;
* "currentHandType": stores the value to indicate who to give cards to during exchange.

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->init( "foo" )</i>

Note: lower in the code there is a line that needs to be removed in order for the game to start. Search for it and remove it now.
$this->setGameStateInitialValue("my_first_global_variable", 0);

Since we changed the db, 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>

Code Rev [https://github.com/elaskavaia/bga-heartsla/tree/acd1926a6c09dc9afd0752cb6b78eef17c5dfe5c]

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 "Start the game initialization" comment.
<pre>
// Init global values with their initial values

// Note: hand types: 0 = give 3 cards to player on the left
// 1 = give 3 cards to player on the right
// 2 = give 3 cards to player opposite
// 3 = keep cards
$this->setGameStateInitialValue( 'currentHandType', 0 );

// Set current trick color to zero (= no trick color)
$this->setGameStateInitialValue( 'trickColor', 0 );

// Mark if we already played hearts during this hand
$this->setGameStateInitialValue( 'alreadyPlayedHearts', 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.
<pre>
// Create cards
$cards = [];
foreach (self::$CARD_SUITS as $suit => $suit_info) {
// spade, heart, diamond, club
foreach (self::$CARD_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 $this->colors.
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

<pre>
self::$CARD_SUITS = [
1 => [
'name' => clienttranslate('Spade'),
],
2 => [
'name' => clienttranslate('Heart'),
],
3 => [
'name' => clienttranslate('Club'),
],
4 => [
'name' => clienttranslate('Diamond'),
]
];

self::$CARD_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 declared these fields in the class
private static array $CARD_SUITS;
private static array $CARD_TYPES;

== Full game model synchronisation ==

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. 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', $current_player_id );

// 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 .js file in the setup function (which is the receiver of getAllDatas) replace our hack of putting 5 of Hearts directly into the hand with:

<pre>
// Cards in player's hand
for ( var i in this.gamedatas.hand) {
var card = this.gamedatas.hand[i];
var color = card.type;
var value = card.type_arg;
this.playerHand.addToStockWithId(this.getCardUniqueId(color, value), card.id);
}

// Cards played on table
for (i in this.gamedatas.cardsontable) {
var card = this.gamedatas.cardsontable[i];
var color = card.type;
var value = card.type_arg;
var player_id = card.location_arg;
this.playCardOnTable(player_id, color, value, card.id);
}
</pre>

This should show hand and tableau cards now, except we are missing the '''playCardOnTable''' function. So find the '''getCardUniqueId''' function which
should be in the utilities section and add this after it:

<pre>
playCardOnTable : function(player_id, color, value, card_id) {
// player_id => direction
this.addTableCard(value, color, player_id, player_id);

if (player_id != this.player_id) {
// Some opponent played a card
// Move card from player panel
this.placeOnObject('cardontable_' + player_id, 'overall_player_board_' + player_id);
} else {
// You played a card. If it exists in your hand, move card from there and remove
// corresponding item

if ($('myhand_item_' + card_id)) {
this.placeOnObject('cardontable_' + player_id, 'myhand_item_' + card_id);
this.playerHand.removeFromStockById(card_id);
}
}

// In any case: move it to its final destination
this.slideToObject('cardontable_' + player_id, 'playertablecard_' + player_id).play();
},
</pre>

For this to work we also need to define the addTableCard
<pre>
addTableCard(value, color, card_player_id, playerTableId) {
const x = value - 2;
const y = color - 1;
document.getElementById('playertablecard_' + playerTableId).insertAdjacentHTML('beforeend', `
<div class="card cardontable" id="cardontable_${card_player_id}" style="background-position:-${x}00% -${y}00%"></div>
`);
},
</pre>

What this does is basically create another card object, because if it is not our card it's not in our hand (Stock) so
we have to create it out of thin air. Now we have an object with an id of 'cardontable_' + player_id. Depending
on who is playing it we either place it on the player miniboard or in hand (and remove it from hand stock). Then we animate the card move.

We also should fix our .css file now to add style for cardontable and REMOVE background for playertablecard which really is a placeholder div and not a card. (Don't miss the remove step; it will be all screwy if you do!)

<pre>
.playertablecard {
display: inline-block;
position: relative;
margin-top: 5px;
width: 72px;
height: 96px;
/* we remove background-image here */
}

/*** cards on table ***/

.cardontable {
position: absolute;
width: 72px;
height: 96px;
background-image: url('img/cards.jpg');
}
</pre>

Now to test that it actually works let's deal cards to players during game initialization:

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 ) {
$cards = $this->cards->pickCards(13, 'deck', $player_id);
}
</pre>

Now when you start the game you should see 13 cards in your hand!

We just need to hook-up clicking on card and test if our playCardOnTable works.

Find onPlayerHandSelectionChanged function in the JS file, we should have logging there like console.log("on playCard "+card_id);
So after that insert this (Note: this code is for testing we will replace it with server interaction after we test it.):
<pre>
console.log("on playCard "+card_id);
// type is (color - 1) * 13 + (value - 2)
var type = items[0].type;
var color = Math.floor(type / 13) + 1;
var value = type % 13 + 2;

this.playCardOnTable(this.player_id,color,value,card_id);
</pre>
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]]

Code Rev [https://github.com/elaskavaia/bga-heartsla/tree/0ed80e254a6d0c29f267b308d1c2016db90fd4f6]

== State Machine ==

Now we need to create a game state machine. So the states are (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 is selected who will start a new trick ("newTrick")
* 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) ("nextHand")

The state handling spread across multiple files, so you have to make sure all pieces are connected together.
The state machine states.php defines all the states, and function handlers on php side in a form of string,
and if any of these functions are not implemented it would be very hard to debug because it will break in random places.

So .states.php (remove all template states and replace with these)

<pre>
$machinestates = array(
/// New hand
2 => array(
"name" => "newHand",
"description" => "",
"type" => "game",
"action" => "stNewHand",
"updateGameProgression" => true,
"transitions" => array( "" => 30 )
),

21 => array(
"name" => "giveCards",
"description" => clienttranslate('Some players must choose 3 cards to give to ${direction}'),
"descriptionmyturn" => clienttranslate('${you} must choose 3 cards to give to ${direction}'),
"type" => "multipleactiveplayer",
"action" => "stGiveCards",
"args" => "argGiveCards",
"possibleactions" => array( "actGiveCards" ),
"transitions" => array( "giveCards" => 22, "skip" => 22 )
),

22 => array(
"name" => "takeCards",
"description" => "",
"type" => "game",
"action" => "stTakeCards",
"transitions" => array( "startHand" => 30, "skip" => 30 )
),

// Trick

30 => array(
"name" => "newTrick",
"description" => "",
"type" => "game",
"action" => "stNewTrick",
"transitions" => array( "" => 31 )
),
31 => array(
"name" => "playerTurn",
"description" => clienttranslate('${actplayer} must play a card'),
"descriptionmyturn" => clienttranslate('${you} must play a card'),
"type" => "activeplayer",
"possibleactions" => array( "actPlayCard" ),
"transitions" => array( "playCard" => 32 )
),
32 => array(
"name" => "nextPlayer",
"description" => "",
"type" => "game",
"action" => "stNextPlayer",
"transitions" => array( "nextPlayer" => 31, "nextTrick" => 30, "endHand" => 40 )
),

// End of the hand (scoring, etc...)
40 => array(
"name" => "endHand",
"description" => "",
"type" => "game",
"action" => "stEndHand",
"transitions" => array( "nextHand" => 2, "endGame" => 99 )
),

);
</pre>

The full details on these fields are in [[Your_game_state_machine:_states.inc.php]].

But basically we have Player states, in which a human player has to perform an "action" by pressing some button in the UI or selecting some game item, which will trigger js handler, which will do an ajax call to the server.

To make it run we have to define all the handler functions that we referenced in states, which are - one function for state arguments argGiveCards, 4 functions for robot states (where the game performs some action)
and 1 function for player actions handling.
In Game.php, find 'Game state arguments' section and paste this in:
<pre>
function argGiveCards() {
return [];
}
</pre>

This normally passes some parameters to states, but we don't need anything yet. It's good to have a placeholder there anyway, so we can fix it later.
Important: even when it's a stub, this function must return an array not a scalar.

Let's do stubs for other functions, find the game state actions section in Game.php file and insert these (replace all st* method defined in template)
<pre>
function stNewHand() {
// Take back all cards (from any location => null) to deck
$this->cards->moveAllCardsInLocation(null, "deck");
$this->cards->shuffle('deck');
// Deal 13 cards to each players
// Create deck, shuffle it and give 13 initial cards
$players = $this->loadPlayersBasicInfos();
foreach ( $players as $player_id => $player ) {
$cards = $this->cards->pickCards(13, 'deck', $player_id);
// Notify player about his cards
$this->notify->player($player_id, 'newHand', '', array ('cards' => $cards ));
}
$this->setGameStateValue('alreadyPlayedHearts', 0);
$this->gamestate->nextState("");
}

function stNewTrick() {
// New trick: active the player who wins the last trick, or the player who own the club-2 card
// Reset trick color to 0 (= no color)
$this->setGameStateInitialValue('trickColor', 0);
$this->gamestate->nextState();
}

function stNextPlayer() {
// Active next player OR end the trick and go to the next trick OR end the hand
if ($this->cards->countCardInLocation('cardsontable') == 4) {
// This is the end of the trick
// Move all cards to "cardswon" of the given player
$best_value_player_id = $this->activeNextPlayer(); // TODO figure out winner of trick
$this->cards->moveAllCardsInLocation('cardsontable', 'cardswon', null, $best_value_player_id);

if ($this->cards->countCardInLocation('hand') == 0) {
// End of the hand
$this->gamestate->nextState("endHand");
} else {
// End of the trick
$this->gamestate->nextState("nextTrick");
}
} else {
// Standard case (not the end of the trick)
// => just active the next player
$player_id = $this->activeNextPlayer();
$this->giveExtraTime($player_id);
$this->gamestate->nextState('nextPlayer');
}
}

function stEndHand() {
$this->gamestate->nextState("nextHand");
}

</pre>
Important: All state actions game or player must end with state transition (or thrown exception). Also make sure it's ONLY one state transition,
if you accidentally fall through after state transition and do another one it will be a real mess and head scratching for long time.

Now find 'player actions' section and paste this code there (replace all existing act* functions)
<pre>
function actPlayCard(int $card_id) {
$player_id = $this->getActivePlayerId();
throw new \BgaUserException(clienttranslate('Not implemented: ${player_id} plays ${card_id}'), [
"player_id" => "$player_id",
"card_id" => $card_id,
]);

}
</pre>
We won't implement it yet but throw an exception which we will see if interaction is working properly

If your game is running you have to exit it. When we change state machine in the middle of the game usually it won't be good.

Now the game should start but it would not be any different than before because we have to implement actual interactions.
It's good to check if it's still working though (and if it was running before you have to exit because we changed state machine and normally it will break stuff).

NOTE: When you play a card, you will not yet get the "Not implemented" message. That is added in the next section.

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
<pre>
onUpdateActionButtons: function (stateName, args) {
console.log("onUpdateActionButtons: " + stateName, args);

if (this.isCurrentPlayerActive()) {
switch (stateName) {
case "playerTurn":
break;
}
}
},
</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.

Eventhough we can it ajax call the API now called "bgaPerformAction" and this is what you should be using.

So in .js code replace onPlayerHandSelectionChanged with
<pre>
onPlayerHandSelectionChanged : function() {
var items = this.playerHand.getSelectedItems();

if (items.length > 0) {
var action = 'actPlayCard';
if (this.checkAction(action, true)) {
// Can play a card
var card_id = items[0].id;
this.bgaPerformAction(action, {
card_id : card_id,
});

this.playerHand.unselectAll();
} else if (this.checkAction('actGiveCards')) {
// Can give cards => let the player select some cards
} else {
this.playerHand.unselectAll();
}
}
},
</pre>

Now when you click on card you should get a server response: Not implemented...

Lets implement it, in Game.php
<pre>

function actPlayCard(int $card_id) {
$player_id = $this->getActivePlayerId();
$this->cards->moveCard($card_id, 'cardsontable', $player_id);
// XXX check rules here
$currentCard = $this->cards->getCard($card_id);
// And notify
$this->notify->all('playCard', clienttranslate('${player_name} plays ${value_displayed} ${color_displayed}'), array (
'i18n' => array ('color_displayed','value_displayed' ),'card_id' => $card_id,'player_id' => $player_id,
'player_name' => $this->getActivePlayerName(),
'value' => $currentCard ['type_arg'],
'value_displayed' => self::$CARD_TYPES [$currentCard ['type_arg']] ['name'],
'color' => $currentCard ['type'],
'color_displayed' => self::$CARD_SUITS [$currentCard ['type']] ['name'] ));
// Next player
$this->gamestate->nextState('playCard');
}

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

<pre>
setupNotifications : function() {
console.log('notifications subscriptions setup');
// table of notif type to delay in milliseconds
const notifs = [
['newHand', 1],
['playCard', 100],
];

notifs.forEach((notif) => {
dojo.subscribe(notif[0], this, `notif_${notif[0]}`);
this.notifqueue.setSynchronous(notif[0], notif[1]);
});

},

notif_newHand : function(notif) {
// We received a new full hand of 13 cards.
this.playerHand.removeAll();

for ( var i in notif.args.cards) {
var card = notif.args.cards[i];
var color = card.type;
var value = card.type_arg;
this.playerHand.addToStockWithId(this.getCardUniqueId(color, value), card.id);
}
},

notif_playCard : function(notif) {
// Play a card on the table
this.playCardOnTable(notif.args.player_id, notif.args.color, notif.args.value, notif.args.card_id);
},
</pre>

Now it actually works through the server when you click on card - the move is recorded. If you test it now 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 we need to send notification about it
and have a handler for it

So in Game.php file add notification in stNextPlayer function after moveAllCardsInLocation call:

<pre>
// Notify
// 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 = $this->loadPlayersBasicInfos();
$this->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']
) );
$this->notify->all( 'giveAllCardsToPlayer','', array(
'player_id' => $best_value_player_id
) );
</pre>

And in .js file add 2 more notification handlers.

This is to subscribe in setupNotifications function
<pre>
const notifs = [
...
['trickWin', 1000],
['giveAllCardsToPlayer', 600],
];
</pre>

And these are handlers
<pre>
notif_trickWin : function(notif) {
// We do nothing here (just wait in order players can view the 4 cards played before they're gone.
},
notif_giveAllCardsToPlayer : function(notif) {
// Move all cards on table to given table, then destroy them
var winner_id = notif.args.player_id;
for ( var player_id in this.gamedatas.players) {
var anim = this.slideToObject('cardontable_' + player_id, 'overall_player_board_' + winner_id);
dojo.connect(anim, 'onEnd', function(node) {
dojo.destroy(node);
});
anim.play();
}
},
</pre>

So 'trickWin' notification does not do much except it will delay the processing of next notification by 1 second (1000 ms)
and it will log the message (that happens independently of what handler does).
<i>Note: if on the other hand you don't want to log but want to do something else, send an empty message</i>

Now after the trick you see all cards move towards the "player's stash".

== 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 'trickColor' which we already conveniently created.

In Game.php file find the actPlayCard function and add this before notify functions
$currentTrickColor = $this->getGameStateValue( 'trickColor' ) ;
if( $currentTrickColor == 0 )
$this->setGameStateValue( 'trickColor', $currentCard['type'] );

This will make sure we remember the first suit being played, now to use it modify the stNextPlayer function to fix our TODO comment
<pre>
function stNextPlayer() {
// Active next player OR end the trick and go to the next trick OR end the hand
if ($this->cards->countCardInLocation('cardsontable') == 4) {
// This is the end of the trick
$cards_on_table = $this->cards->getCardsInLocation('cardsontable');
$best_value = 0;
$best_value_player_id = null;
$currentTrickColor = $this->getGameStateValue('trickColor');
foreach ( $cards_on_table as $card ) {
// Note: type = card color
if ($card ['type'] == $currentTrickColor) {
if ($best_value_player_id === null || $card ['type_arg'] > $best_value) {
$best_value_player_id = $card ['location_arg']; // Note: location_arg = player who played this card on table
$best_value = $card ['type_arg']; // Note: type_arg = value of the card
}
}
}

// Active this player => he's the one who starts the next trick
$this->gamestate->changeActivePlayer( $best_value_player_id );

// Move all cards to "cardswon" of the given player
$this->cards->moveAllCardsInLocation('cardsontable', 'cardswon', null, $best_value_player_id);

// Notify
// ... same code here 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, also
we want to show that in the log.
In addition scoring can be shown in [[Game_interface_logic:_yourgamename.js#Scoring_dialogs|Scoring Dialog]] using tableWindow notification, but it is a tutorial on its own and you can do it as homework (it is part of original heart game).

so in Game.php our stEndHand function will look like

<pre>
function stEndHand() {
// Count and score points, then end the game or go to the next hand.
$players = $this->loadPlayersBasicInfos();
// Gets all "hearts" + queen of spades

$player_to_points = array ();
foreach ( $players as $player_id => $player ) {
$player_to_points [$player_id] = 0;
}
$cards = $this->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) {
$this->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 ($this->playerScore->getMin() <= -100) {
// Trigger the end of the game !
$this->gamestate->nextState("endGame");
return;
}

$this->gamestate->nextState("nextHand");
}
</pre>

So it should more less work now, including end of game condition. Try to play it!

== Additional stuff ==

The following things were not implemented and can add them yourself by looking at the code of original hearts game:

* Remove debug code from setupNewGame to deal cards, cards are now dealt in stNewHand state handler
* Rule checking and rule enforcements in actPlayCard function
* Start scoring with 100 points each and end when <= 0
* Fix scoring rules with Q of spades and 26 point reverse scoring
* First player one with 2 club
* Add progress handling
* 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:Heartstutorial-1.png

2025-10-04T23:37:11Z

ShaharHarshuv: