Board Game Arena - User contributions [en]

Tools and tips of BGA Studio

2023-11-19T09:10:57Z

Xmakina: /* State machine diagram generation tool */ Add link for new State Machine generator

{{Studio_Framework_Navigation}}

== Server Tools and Tips ==
=== Starting a game in one click ===

To start a game:
* Go to Play now and configure game type: Simple game -> Turn-based -> Manual
* Select your game and click on "Create".
* If you want to play a game with 3 players, specify that you want a maximum of 3 players at this table.
* Click on "Express Start".

=== Stopping a game in one click ===

* Click on the "menú" icon on the top right of the screen.
* Click on "Express Stop" ("Quit this game" if playing a solo game).

=== Switching between users ===

When running a game on Studio, you can use the little red arrow near each player's name to open a new tab with this player's perspective.
You can also modify the URL to view the table as any user you want (changing &testuser=myid in the URL), allowing to easily test as a spectator.

=== Access to game database and Logs ===

At the bottom of the game area, there is section without a title containing 3 useful links:

Go to game database • BGA request&SQL logs • BGA unexpected exceptions logs

* "Go to game database" link is an immediate access to the PhpMyAdmin tool to view/edit the tables of the current game
* BGA request&SQL logs - link to your studio PHP log - all tables, all severities. Anything you print using debugging and tracing functions from PHP and some framework logs
* BGA unexpected exceptions logs - same log as above but only severity warning and higher

See [[Practical debugging]] for more info about it.

=== Save & restore state ===

Using links of this section, you can save the complete current (database) state of your game, then restore it later.

This is particularly useful when you want to develop a part of the game that is difficult to reproduce: you just have to save the situation just before, and then restore it until this part works fine.

We provide you 3 "slots": 1, 2 and 3. This way, you can save 3 different game situations.

Limits:
* the "restore" function does not work anymore when the game is over.
* a saved situation from a given table cannot be restored in another table.
* when you "restore" a situation, the current browser page is refreshed to reflect the updated game situation, but you have to refresh you other tabs/pages manually.

=== Input/Output debugging section ===

This section shows you:
* The AJAX calls made by your game interface to the game server. AJAX calls (outputs) begins with ">"
* The notifications received by your game interface. Notifications (inputs) begins with "<".

Note: if you click on some notification title, you can resend it immediately to the user interface.

=== Run PHP functions from the chat ===

On BGA Studio, you can directly run a PHP method from the table chat. The production environment does not allow PHP methods to be called from the table chat.

For example, if on your PHP you have this method:

function giveMoneyToPlayer($player_id, $amount) { ... }

You can call this method directly from the chat like this:

giveMoneyToPlayer(2564,2)

Note: this is not a real php statement, you cannot use self::, you cannot use ";" at the end and you cannot use quotes,
if you need to pass a string skip the quotes, like this

giveToActivePlayer(money,2)

What if you want something more complex like passing an array? Or calling other function? Just create another function in php for that and use it. I suggest to use prefix debug for all such functions.
function debug_q($x) {
$player_id = $this->getActivePlayerId();
$this-> giveMoneyToPlayer($player_id, $x);
}

=== Zombify a player ===

Call this from chat (studio only) to zombify current player (who is "thinking")
timeout()

Never call from game code.

=== Stopping Hanging Game ===

If game is hanging and you cannot enter it to stop you can type this URL (replace 12345 with your table number),
which should bring you to a place where you can stop it without entering:

<nowiki>https://studio.boardgamearena.com/#!table?table=12345</nowiki>

== Desktop and Web Tools ==
=== Code Editors and IDEs ===

==== Visual Studio Code ====
Microsoft Visual Studio Code is light weight IDE/Editor. All desktops.
https://code.visualstudio.com

See [[Setting up BGA Development environment using VSCode]]

==== Eclipse For PHP Developers ====

Eclipse PHP package can be starting point for development you need. You may also want to
install Tern JS plugins to understand dojo style JS. All desktops.
https://projects.eclipse.org/projects/tools.pdt

==== Gedit (Ubuntu) ====
'''Edit TPL'''
To edit TPL with HTML code highlightings in Gedit under Ubuntu:

find gtksourceview directory in /usr/share, depending on your version (2.0, 3.0,...).
<br>
Here it's 3.0, then type in a terminal window:
<pre>
sudo gedit /usr/share/gtksourceview-3.0/language-specs/html.lang
</pre>

then find 'globs' section, and change:

<pre>
<property name="globs">*.html;*.htm;*.tpl</property>
</pre>

=== File Sync ===

NOTE: If you use VS Code you don't need to use methods below, use one of the sync methods provided by VS Code extensios. See [[Setting up BGA Development environment using VSCode]]

==== File Sync on Windows ====

Install [http://winscp.net/ WinSCP]. Map a remote directory to a local one and enable continuous sync (one way). You need SFTP password you get when you registered dev account.

==== File Sync on Linux ====

===== Option 1 - Nautilus (file manager) =====
You can just use Nautilus "connect to a server" function with URL sftp://1.studio.boardgamearena.com
Then you'll get a mounted local folder mapping your studio folder and you can use any editor you like without further need for sync. Downside - if connection goes down you cannot work on source code, no local copy.

===== Option 2 - sftp and rsync =====
This setup will sync in the background (continious sync) when file is saved, after you set it up and start just save your files and they be on server before you can hit refresh.

<pre>
#!/bin/bash
BASEDIR=`dirname $0`
REMOTE=$BASEDIR/remote
LOCAL=$BASEDIR/workspace
GAME=mygamenamehere

#mount remote
fusermount -u $REMOTE #this unmounts dir
#this asssumes your default ssh key is uploaded to studio
sshfs myusernamehere@1.studio.boardgamearena.com: $REMOTE

#this starts auto-sync from local to remote mount
killall lsyncd
lsyncd -delay 1 -rsync $LOCAL/$GAME/ $REMOTE/$GAME
</pre>

This can be able run on startup, so you don't have to do anything manually. However sshfs is not very stable you
have to kill and restart it sometimes. And remote goes away sometimes due to connection issues with studio.
In this case its handy to have a local copy, which is what lsyncd for.

You can also sync on demand (from a build script or editor command) using
rsync -vlrt $LOCAL/$GAME/ $REMOTE/$GAME

Note: is insecure way of running sshfs
echo LongDevPassword | sshfs -o password_stdin ...

===== Option 3 - lftp =====

[https://lftp.yar.ru/ lftp] is a fast command-line file transfer program. It supports parallel threads, transferring multiple files at a time.

* Linux: Install using your package manager, for example: '''sudo apt-get install lftp'''
* Mac: Install [https://brew.sh/ Homebrew], then install lftp using '''brew install lftp'''

To upload your project to BGA studio, use the "mirror" command like this:

'''lftp sftp://<span style="color:blue">myuser</span>:<span style="color:red">mypassword</span>@1.studio.boardgamearena.com/ -e "mirror --reverse --parallel=10 --delete <span style="color:orange">/local/path/to/myproject</span>/ <span style="color:green">myproject</span>/; exit"

Be sure to include the trailing '''/''' after both directory names.

By default, if a file already exists on BGA Studio with the same time + size it assumed to be the same and won't be transferred. This makes the transfer process much quicker after the first time. If you're working with multiple developers on the same project and you find that it is transfers all files every time, you may want to add the option '''--ignore-time''' (if a file already exist on BGA Studio with the same size it is assumed to be the same and won't be transferred). Read [https://lftp.yar.ru/lftp-man.html the manual] for more details.

This is one time sync (unless I am missing something this does not do continious sync?)

=== Debuggers ===

Browser is the best tool for JS/HTML5 debugging, see [[Practical debugging]] for details.

=== Version Control ===
Studio provides svn for you code on server, there are some limited abilities there to see history and restore. I recommend to also keep your code in another repository, which allows keeping more fine-grained history and can simplify collaboration.

A quick option is to use a local repo, which you can sync to cloud or backup.

Other option is to host source code on github. If you do, the convention is to use github.com/<yourname>/bga-<yourgame>. It is recommended to add the [https://github.com/topics/boardgamearena boardgamearena] tag and add your repo to the list on the [[BGA_Code_Sharing]] page.

If you publish the source somewhere externally, make sure you '''don't post high-res publisher graphics''', only web resources, and post a separate license for graphics files. Also, '''don't include a file with your sftp password''' (github is automatically crawled for passwords by hackers; a hacking attempt occurred on BGA studio for this reason in June 2020).

You can also configure github to automatically deploy to BGA whenever you push to a branch. See [https://forum.boardgamearena.com/viewtopic.php?f=12&t=13370&start=10#p59537 this forum post] for instructions.

=== PHP CLI ===
Its handy to have php cli (command line) tools install to run php locally, so you can test some stuff without deployment cycle, or create some scripts that generate code or markup.

=== Image Manipulation ===
==== ImageMagick ====
Handy set of image manipulation '''command line''' tools, useful to for example to stitch together bunch of images and re-size, to use as sprite (in Stock component for example). I.e. you got a graphics file from publisher where every tile is 600x600 PNG file in separate file. You want .jpg instead of .png to make it not like 20Mb, and combine all images in one column and re-size to 128x128:

(Linux example)
/usr/bin/montage `ls Tiles*.png` -tile 1 -geometry 128x128+0+0 out/tiles128.jpg

The order of the images will match the 'ls' order. If needed change the filenames if you need a specific order.

https://www.imagemagick.org/script/download.php

==== Gimp ====

GUI tool, very complex but will do ALL what you possibly need to do with game graphics

https://www.gimp.org/

==== Shrinking ====

Shrink images without loss of quality https://tinypng.com/ or http://www.iloveimg.com/

==== PDF Scrapper ====
extract images from PDF file (i.e. game rulebook) :

https://www.ilovepdf.com/

http://www.extractpdf.com/

On linux tool that does it in command line "pdfimages"

==== Rename/Copy project ====

You can now override your project with any other project using Studio Control Panel.

Alternatively there is a script available in sharedcode project to do the renaming which can be called in command line if you have php command line installed.
You need to have php clt (command line interface) installed, then you can download script and run it.

https://github.com/elaskavaia/bga-sharedcode/blob/master/misc/bgaprojectrename.php

Usage:
php bgaprojectrename.php <originalProjectPath> <copyOfProjectRenamedPath>

Example on how to call it in command line if you project name is "heartsmyproject"

php7.0 git/bga-sharedcode/tools/bgaprojectrename.php remote/hearts/ remote/heartsmyproject/

==== BGA Workbench ====

PHP library providing tools to help manage BGA Studio projects including deployment and test utilities. https://github.com/danielholmes/bga-workbench

=== Testing and validation tools ===

* Run static analysis on your project to detect common problem and translation issues - project check - available from control panel - manage games - <your project> - Check project (blue button left middle)
* Check if web feature is supported https://caniuse.com/
* PHP: https://phpcodechecker.com/
* JS: http://esprima.org/demo/validate.html
* CSS: http://jigsaw.w3.org/css-validator/

=== State machine diagram generation tool ===

You can easily generate a state machine diagram from your states.inc.php using the dot language (https://graphviz.org/) via a PHP script.

To do so:
* download the php script from the bga-sharedcode git repo located here https://github.com/elaskavaia/bga-sharedcode/blob/master/misc/generate_state_diagram.php and place it into your project root (on the same level as states.inc.php)
* run the script locally: "php.exe generate_state_diagram.php > graph.dot"
* open the generated dot file for visualization in visual studio code using the "Graphviz Interactive Preview" extension
* alternatively install graphiz (https://graphviz.org/download/) and generate an image file by running the following command "dot -Tpng -o graph.png graph.dot"

Here is an example of running the generation script on the hearts game from the tutorial:

[[File:State_machine_diagram_dot.png]]

'''Legend:'''
* states of type game appear in yellow
* states of type activeplayer appear in blue
* states of type multipleactiveplayer appear in green
Once you have this state machine, you can use it to generate boilerplate code using the [https://github.com/xmakina/bga-statemachinegenerator BGA State Machine Generator]

== Other useful tools ==

* Website with bunch of textures and sounds http://www.grsites.com/archive/textures/
* Shrink images without loss of quality https://tinypng.com/ or http://www.iloveimg.com/ (recommended by Gregory Isabelli)
* CSS shapes https://css-tricks.com/examples/ShapesOfCSS/
* PDF Scraper - extract images - http://www.extractpdf.com/
* Hexagonal Grids (from Red Blob Games) - https://www.redblobgames.com/grids/hexagons/
* CSS tools (shades, shapes, textures) - https://dev.to/lissy93/super-useful-css-resources-1ba3
* Color blind pallette https://jfly.uni-koeln.de/color/
* CSS stroked text https://blog.logrocket.com/create-beautiful-stroked-text-css/
* CSS box model and SVG images https://www.freecodecamp.org/news/how-to-use-css-box-model-and-style-svg-images/

== Client Tips ==

=== Speed up game re-loading by disabling Input/Output debug section ===

Development UI have few sections for debugging only, such as 'Input/Output debugging section'. Loading this data will significantly slow down
your reload. I did some profiling and my reloading (i.e. F5) took 14 seconds, 12 of which it was dealing with loading this section.
If you not using it you can disable it. In your JavaScript code, in the begging of 'setup' method add this code

dojo.destroy('debug_output');

That should get rid of this section and overhead associated with loading it (it may have some other side-effects, I have not explored all of them)

=== Speed up CSS development and layout ===

Syncing files to server and refreshing is relative fast but still can take up to 20 seconds which is annoying.
If you working
a lot on css/images/layout you can speed it up by copying html in some state of the game to your local folder.
I.e. in your project folder create directory misc/ and save your html as misc/test.html and changing path to css to load from local disk (and it will load your images to from local disk as well).
I.e. find something like

<link rel="stylesheet" type="text/css" href="http://1.studio.boardgamearena.com:8081/data/themereleases/151226-1240/games/mygame/999999-9999/mygame.css"/>

and replace with
<link rel="stylesheet" type="text/css" href="../mygame.css"/>

You project structure will look like this

mygame
img/ <-- your images
mygame.css <-- your original css
...
misc/
test.html <-- your test html

It is a bit tricky to save html exact state, if you do save as it also pulls all resources sometimes.

[[Category:Studio]]

Tutorial hearts

2023-11-10T09:21:51Z

Xmakina: /* Layout and Graphics */ update tutorial image to reflect what is actually shown

{{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.
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 heartsYOURNAME_heartsYOURNAME.tpl, 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).

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

<b>Attention!!!</b> Very important note about reloading, if you don't remember this you may spent hours debugging. Browser caches .css files and 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. The full game can be found in your FTP home folder.

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

// 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.png''' 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>

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

== 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. Project hearts is mounted to your home directory on bga server.
<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]].

Edit .tpl to add some divs to represent player table and hand area

<pre>
<div id="myhand_wrap" class="whiteblock">
<h3>My Hand</h3>
<div id="myhand">
</div>
</div>
</pre>

If you refresh you should see now white area with My Hand title.

[[File:Heartsla-tpl2.png]]

Now lets add a card into the hand, just so you can feel it. Edit .tpl 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 edit CSS remember that you have to FORCE-reload page, i.e. Ctrl-F5, otherwise its cached.
<i>Same when you change existing graphics files</i>.

You should see this:

[[File:Heartsla-tpl3.png]]

Awesome! Now lets do the rest of layout.

There are few ways of how html could have been generated, you could have start with nothing and generate
all by java script. Or you could have started with complete game markup in html and make java script just hide and move pieces around. BGA framework provides also a third way which is mix of both plus template engine to generate HTML using php. So lets do that.

Change .tpl file to have this inside
<pre>
<div id="playertables">


<div class="playertable whiteblock playertable_{DIR}">
<div class="playertablename" style="color:#{PLAYER_COLOR}">
{PLAYER_NAME}
</div>
<div class="playertablecard" id="playertablecard_{PLAYER_ID}">
</div>
</div>


</div>

<div id="myhand_wrap" class="whiteblock">
<h3>{MY_HAND}</h3>
<div id="myhand">
</div>
</div>
</pre>

What we did is we added "block" player, it is marked up using html comments. {VAR} notation is used
to inject variables and
<pre>

inside

</pre>
effectively allows us to do template loops.

In .view.php insert this code after 'Place your code below' comment

<pre>
$template = self::getGameName() . "_" . self::getGameName();

$directions = array( 'S', 'W', 'N', 'E' );

// this will inflate our player block with actual players data
$this->page->begin_block($template, "player");
foreach ( $players as $player_id => $info ) {
$dir = array_shift($directions);
$this->page->insert_block("player", array ("PLAYER_ID" => $player_id,
"PLAYER_NAME" => $players [$player_id] ['player_name'],
"PLAYER_COLOR" => $players [$player_id] ['player_color'],
"DIR" => $dir ));
}
// this will make our My Hand text translatable
$this->tpl['MY_HAND'] = self::_("My hand");
</pre>

What it does is for each player we have it will replicate the html between  and  tags, substituting the variable denoted by {XXX}
with the values you provide. The DIR variable in this case we pulling from directions array (where array_shift will take first element and remove it from the array).

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

#playertables {
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 .css and 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 css and 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 hearts.js file:
<pre>
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/stock" /// <==== HERE
],
</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:
<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".

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>
onPlayerHandSelectionChanged: function() {
var items = this.playerHand.getSelectedItems();

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

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

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

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

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.

Next we finally get into .game.php class, 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.
<pre>
parent::__construct();
self::initGameStateLabels( array(
"currentHandType" => 10,
"trickColor" => 11,
"alreadyPlayedHearts" => 12,
) );

$this->cards = self::getNew( "module.common.deck" );
$this->cards->init( "card" );
</pre>

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>

At this point I would 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/e3a049257b592ff6167688d4d344f8a83d349b08]

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
self::setGameStateInitialValue( 'currentHandType', 0 );

// Set current trick color to zero (= no trick color)
self::setGameStateInitialValue( 'trickColor', 0 );

// Mark if we already played hearts during this hand
self::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 = array ();
foreach ( $this->colors as $color_id => $color ) {
// spade, heart, diamond, club
for ($value = 2; $value <= 14; $value ++) {
// 2, 3, 4, ... K, A
$cards [] = array ('type' => $color_id,'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 material.inc.php and this way it can be accessed from all .php files (and .js if you send it via getAllDatas()).
We will edit this file now by adding these lines

<pre>
$this->colors = array(
1 => array( 'name' => clienttranslate('spade'),
'nametr' => self::_('spade') ),
2 => array( 'name' => clienttranslate('heart'),
'nametr' => self::_('heart') ),
3 => array( 'name' => clienttranslate('club'),
'nametr' => self::_('club') ),
4 => array( 'name' => clienttranslate('diamond'),
'nametr' => self::_('diamond') )
);

$this->values_label = array(
2 =>'2',
3 => '3',
4 => '4',
5 => '5',
6 => '6',
7 => '7',
8 => '8',
9 => '9',
10 => '10',
11 => clienttranslate('J'),
12 => clienttranslate('Q'),
13 => clienttranslate('K'),
14 => clienttranslate('A')
);
</pre>

Where $this->colors will define Suit labels and $this->values_label will define value labels.
If you noticed, we have two of each label for suits. This is because sometimes we need translated values on the php
side and sometimes we don't. In this case '''nametr''' will return a translated value in php, which is only useful when you throw exceptions to show the right strings. If you pass a value to the client via notification you should always use untranslated strings, and the client will translate it. 'clienttranslate' marks the value for translation but does not actually change it for php. For more about this wonderful translation stuff see [[Translations]].

== 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
dojo.place(this.format_block('jstpl_cardontable', {
x : this.cardwidth * (value - 2),
y : this.cardheight * (color - 1),
player_id : player_id
}), 'playertablecard_' + 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 add a card template in the .tpl file
<pre>
// Javascript HTML templates

var jstpl_cardontable = '<div class="cardontable" id="cardontable_${player_id}" style="background-position:-${x}px -${y}px">\
</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. The technique to do that is to implement a Javascript template object defined in the .tpl file with some
parameters, which will basically create a "div" string (yes you could have used string concatenation but it would not be fancy).
Now dojo.place places it (the div) on top of a placeholder. 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 = self::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:
<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>
Note: this code is for testing we will replace it with server interaction after we test it.

Now if you force reload (because we changed .css before) 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/01d4e2f595fd14c2adcc97a957d21bb2766f78a8]

== State Machine ==

Now we need to create a game state machine. So the states are:

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

In addition players can exchange cards so we need two more states for that but we will skip it for now.

The state handling spread across 4 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

<pre>
$machinestates = array(

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

/// 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( "giveCards" ),
"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( "playCard" ),
"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 )
),

// Final state.
// Please do not modify.
99 => array(
"name" => "gameEnd",
"description" => clienttranslate("End of game"),
"type" => "manager",
"action" => "stGameEnd",
"args" => "argGameEnd"
)

);
</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 into API defined
by .action.php file. All functions in this file are API between client and server and have very simple
and repetitive structures. In this case there are only two actions player can do - play a card or pass cards to other player. So these 2 functions go into .action.php file, we will only define one now since we have not implemented card passing states yet:

<pre>
public function playCard() {
self::setAjaxMode();
$card_id = self::getArg("id", AT_posint, true);
$this->game->playCard($card_id);
self::ajaxResponse();
}
</pre>

Now 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 array ();
}
</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
<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 = self::loadPlayersBasicInfos();
foreach ( $players as $player_id => $player ) {
$cards = $this->cards->pickCards(13, 'deck', $player_id);
// Notify player about his cards
self::notifyPlayer($player_id, 'newHand', '', array ('cards' => $cards ));
}
self::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)
self::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 = self::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 = self::activeNextPlayer();
self::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
<pre>
function playCard($card_id) {
self::checkAction("playCard");
$player_id = self::getActivePlayerId();
throw new BgaUserException(self::_("Not implemented: ") . "$player_id plays $card_id");
}
</pre>
We won't implement it yet but throw an exception which we will see if interaction is working properly

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)

== 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 = 'playCard';
if (this.checkAction(action, true)) {
// Can play a card
var card_id = items[0].id;
this.ajaxcall("/" + this.game_name + "/" + this.game_name + "/" + action + ".html", {
id : card_id,
lock : true
}, this, function(result) {
}, function(is_error) {
});

this.playerHand.unselectAll();
} else if (this.checkAction('giveCards')) {
// 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 playCard($card_id) {
self::checkAction("playCard");
$player_id = self::getActivePlayerId();
$this->cards->moveCard($card_id, 'cardsontable', $player_id);
// XXX check rules here
$currentCard = $this->cards->getCard($card_id);
// And notify
self::notifyAllPlayers('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' => self::getActivePlayerName(),'value' => $currentCard ['type_arg'],
'value_displayed' => $this->values_label [$currentCard ['type_arg']],'color' => $currentCard ['type'],
'color_displayed' => $this->colors [$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');

dojo.subscribe('newHand', this, "notif_newHand");
dojo.subscribe('playCard', this, "notif_playCard");

},

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 = self::loadPlayersBasicInfos();
self::notifyAllPlayers( 'trickWin', clienttranslate('${player_name} wins the trick'), array(
'player_id' => $best_value_player_id,
'player_name' => $players[ $best_value_player_id ]['player_name']
) );
self::notifyAllPlayers( '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>
dojo.subscribe( 'trickWin', this, "notif_trickWin" );
this.notifqueue.setSynchronous( 'trickWin', 1000 );
dojo.subscribe( 'giveAllCardsToPlayer', this, "notif_giveAllCardsToPlayer" );
</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 playCard function and add this before notify functions
$currentTrickColor = self::getGameStateValue( 'trickColor' ) ;
if( $currentTrickColor == 0 )
self::setGameStateValue( 'trickColor', $currentCard['type'] );

This will make sure we remember first suit being played, now to use it modify 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 = self::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).

In .js file we need to add one more subscription and notification handler:
dojo.subscribe( 'newScores', this, "notif_newScores" );
in setupNotifications

and
notif_newScores : function(notif) {
// Update players' scores
for ( var player_id in notif.args.newScores) {
this.scoreCtrl[player_id].toValue(notif.args.newScores[player_id]);
}
},
somewhere after. this.scoreCtrl is pre-existing object that shows the scoring and this function will update score values per player from notification argument

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 = self::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) {
$sql = "UPDATE player SET player_score=player_score-$points WHERE player_id='$player_id'";
self::DbQuery($sql);
$heart_number = $player_to_points [$player_id];
self::notifyAllPlayers("points", clienttranslate('${player_name} gets ${nbr} hearts and looses ${nbr} points'), array (
'player_id' => $player_id,'player_name' => $players [$player_id] ['player_name'],
'nbr' => $heart_number ));
} else {
// No point lost (just notify)
self::notifyAllPlayers("points", clienttranslate('${player_name} did not get any hearts'), array (
'player_id' => $player_id,'player_name' => $players [$player_id] ['player_name'] ));
}
}
$newScores = self::getCollectionFromDb("SELECT player_id, player_score FROM player", true );
self::notifyAllPlayers( "newScores", '', array( 'newScores' => $newScores ) );

///// Test if this is the end of the game
foreach ( $newScores as $player_id => $score ) {
if ($score <= -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 playCard 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

[[Category:Studio]]

File:Hearts all rows.png

2023-11-10T09:20:55Z

Xmakina:

Display a list of all players, with a dummy card in each position

File:Hearts Tutorial showing all players.png

2023-11-10T09:19:03Z

Xmakina:

Display a list of all players, with a dummy card in each position

Tutorial hearts

2023-11-10T09:06:46Z

Xmakina: /* Layout and Graphics */ Add hack removal

{{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.
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 heartsYOURNAME_heartsYOURNAME.tpl, 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).

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

<b>Attention!!!</b> Very important note about reloading, if you don't remember this you may spent hours debugging. Browser caches .css files and 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. The full game can be found in your FTP home folder.

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

// 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.png''' 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>

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

== 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. Project hearts is mounted to your home directory on bga server.
<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]].

Edit .tpl to add some divs to represent player table and hand area

<pre>
<div id="myhand_wrap" class="whiteblock">
<h3>My Hand</h3>
<div id="myhand">
</div>
</div>
</pre>

If you refresh you should see now white area with My Hand title.

[[File:Heartsla-tpl2.png]]

Now lets add a card into the hand, just so you can feel it. Edit .tpl 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 edit CSS remember that you have to FORCE-reload page, i.e. Ctrl-F5, otherwise its cached.
<i>Same when you change existing graphics files</i>.

You should see this:

[[File:Heartsla-tpl3.png]]

Awesome! Now lets do the rest of layout.

First, remove <code>background-image</code> from <code>.playertablecard</code>. That was a temporary fix that we don't need any more.

There are few ways of how html could have been generated, you could have start with nothing and generate
all by java script. Or you could have started with complete game markup in html and make java script just hide and move pieces around. BGA framework provides also a third way which is mix of both plus template engine to generate HTML using php. So lets do that.

Change .tpl file to have this inside
<pre>
<div id="playertables">


<div class="playertable whiteblock playertable_{DIR}">
<div class="playertablename" style="color:#{PLAYER_COLOR}">
{PLAYER_NAME}
</div>
<div class="playertablecard" id="playertablecard_{PLAYER_ID}">
</div>
</div>


</div>

<div id="myhand_wrap" class="whiteblock">
<h3>{MY_HAND}</h3>
<div id="myhand">
</div>
</div>
</pre>

What we did is we added "block" player, it is marked up using html comments. {VAR} notation is used
to inject variables and
<pre>

inside

</pre>
effectively allows us to do template loops.

In .view.php insert this code after 'Place your code below' comment

<pre>
$template = self::getGameName() . "_" . self::getGameName();

$directions = array( 'S', 'W', 'N', 'E' );

// this will inflate our player block with actual players data
$this->page->begin_block($template, "player");
foreach ( $players as $player_id => $info ) {
$dir = array_shift($directions);
$this->page->insert_block("player", array ("PLAYER_ID" => $player_id,
"PLAYER_NAME" => $players [$player_id] ['player_name'],
"PLAYER_COLOR" => $players [$player_id] ['player_color'],
"DIR" => $dir ));
}
// this will make our My Hand text translatable
$this->tpl['MY_HAND'] = self::_("My hand");
</pre>

What it does is for each player we have it will replicate the html between  and  tags, substituting the variable denoted by {XXX}
with the values you provide. The DIR variable in this case we pulling from directions array (where array_shift will take first element and remove it from the array).

Reload. If everything went well you should see this:

[[File:Heartsla-tpl4.png]]

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

#playertables {
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 .css and 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 css and 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 hearts.js file:
<pre>
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/stock" /// <==== HERE
],
</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:
<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".

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>
onPlayerHandSelectionChanged: function() {
var items = this.playerHand.getSelectedItems();

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

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

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

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

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.

Next we finally get into .game.php class, 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.
<pre>
parent::__construct();
self::initGameStateLabels( array(
"currentHandType" => 10,
"trickColor" => 11,
"alreadyPlayedHearts" => 12,
) );

$this->cards = self::getNew( "module.common.deck" );
$this->cards->init( "card" );
</pre>

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>

At this point I would 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/e3a049257b592ff6167688d4d344f8a83d349b08]

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
self::setGameStateInitialValue( 'currentHandType', 0 );

// Set current trick color to zero (= no trick color)
self::setGameStateInitialValue( 'trickColor', 0 );

// Mark if we already played hearts during this hand
self::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 = array ();
foreach ( $this->colors as $color_id => $color ) {
// spade, heart, diamond, club
for ($value = 2; $value <= 14; $value ++) {
// 2, 3, 4, ... K, A
$cards [] = array ('type' => $color_id,'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 material.inc.php and this way it can be accessed from all .php files (and .js if you send it via getAllDatas()).
We will edit this file now by adding these lines

<pre>
$this->colors = array(
1 => array( 'name' => clienttranslate('spade'),
'nametr' => self::_('spade') ),
2 => array( 'name' => clienttranslate('heart'),
'nametr' => self::_('heart') ),
3 => array( 'name' => clienttranslate('club'),
'nametr' => self::_('club') ),
4 => array( 'name' => clienttranslate('diamond'),
'nametr' => self::_('diamond') )
);

$this->values_label = array(
2 =>'2',
3 => '3',
4 => '4',
5 => '5',
6 => '6',
7 => '7',
8 => '8',
9 => '9',
10 => '10',
11 => clienttranslate('J'),
12 => clienttranslate('Q'),
13 => clienttranslate('K'),
14 => clienttranslate('A')
);
</pre>

Where $this->colors will define Suit labels and $this->values_label will define value labels.
If you noticed, we have two of each label for suits. This is because sometimes we need translated values on the php
side and sometimes we don't. In this case '''nametr''' will return a translated value in php, which is only useful when you throw exceptions to show the right strings. If you pass a value to the client via notification you should always use untranslated strings, and the client will translate it. 'clienttranslate' marks the value for translation but does not actually change it for php. For more about this wonderful translation stuff see [[Translations]].

== 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
dojo.place(this.format_block('jstpl_cardontable', {
x : this.cardwidth * (value - 2),
y : this.cardheight * (color - 1),
player_id : player_id
}), 'playertablecard_' + 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 add a card template in the .tpl file
<pre>
// Javascript HTML templates

var jstpl_cardontable = '<div class="cardontable" id="cardontable_${player_id}" style="background-position:-${x}px -${y}px">\
</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. The technique to do that is to implement a Javascript template object defined in the .tpl file with some
parameters, which will basically create a "div" string (yes you could have used string concatenation but it would not be fancy).
Now dojo.place places it (the div) on top of a placeholder. 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 = self::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:
<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>
Note: this code is for testing we will replace it with server interaction after we test it.

Now if you force reload (because we changed .css before) 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/01d4e2f595fd14c2adcc97a957d21bb2766f78a8]

== State Machine ==

Now we need to create a game state machine. So the states are:

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

In addition players can exchange cards so we need two more states for that but we will skip it for now.

The state handling spread across 4 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

<pre>
$machinestates = array(

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

/// 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( "giveCards" ),
"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( "playCard" ),
"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 )
),

// Final state.
// Please do not modify.
99 => array(
"name" => "gameEnd",
"description" => clienttranslate("End of game"),
"type" => "manager",
"action" => "stGameEnd",
"args" => "argGameEnd"
)

);
</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 into API defined
by .action.php file. All functions in this file are API between client and server and have very simple
and repetitive structures. In this case there are only two actions player can do - play a card or pass cards to other player. So these 2 functions go into .action.php file, we will only define one now since we have not implemented card passing states yet:

<pre>
public function playCard() {
self::setAjaxMode();
$card_id = self::getArg("id", AT_posint, true);
$this->game->playCard($card_id);
self::ajaxResponse();
}
</pre>

Now 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 array ();
}
</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
<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 = self::loadPlayersBasicInfos();
foreach ( $players as $player_id => $player ) {
$cards = $this->cards->pickCards(13, 'deck', $player_id);
// Notify player about his cards
self::notifyPlayer($player_id, 'newHand', '', array ('cards' => $cards ));
}
self::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)
self::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 = self::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 = self::activeNextPlayer();
self::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
<pre>
function playCard($card_id) {
self::checkAction("playCard");
$player_id = self::getActivePlayerId();
throw new BgaUserException(self::_("Not implemented: ") . "$player_id plays $card_id");
}
</pre>
We won't implement it yet but throw an exception which we will see if interaction is working properly

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)

== 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 = 'playCard';
if (this.checkAction(action, true)) {
// Can play a card
var card_id = items[0].id;
this.ajaxcall("/" + this.game_name + "/" + this.game_name + "/" + action + ".html", {
id : card_id,
lock : true
}, this, function(result) {
}, function(is_error) {
});

this.playerHand.unselectAll();
} else if (this.checkAction('giveCards')) {
// 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 playCard($card_id) {
self::checkAction("playCard");
$player_id = self::getActivePlayerId();
$this->cards->moveCard($card_id, 'cardsontable', $player_id);
// XXX check rules here
$currentCard = $this->cards->getCard($card_id);
// And notify
self::notifyAllPlayers('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' => self::getActivePlayerName(),'value' => $currentCard ['type_arg'],
'value_displayed' => $this->values_label [$currentCard ['type_arg']],'color' => $currentCard ['type'],
'color_displayed' => $this->colors [$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');

dojo.subscribe('newHand', this, "notif_newHand");
dojo.subscribe('playCard', this, "notif_playCard");

},

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 = self::loadPlayersBasicInfos();
self::notifyAllPlayers( 'trickWin', clienttranslate('${player_name} wins the trick'), array(
'player_id' => $best_value_player_id,
'player_name' => $players[ $best_value_player_id ]['player_name']
) );
self::notifyAllPlayers( '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>
dojo.subscribe( 'trickWin', this, "notif_trickWin" );
this.notifqueue.setSynchronous( 'trickWin', 1000 );
dojo.subscribe( 'giveAllCardsToPlayer', this, "notif_giveAllCardsToPlayer" );
</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 playCard function and add this before notify functions
$currentTrickColor = self::getGameStateValue( 'trickColor' ) ;
if( $currentTrickColor == 0 )
self::setGameStateValue( 'trickColor', $currentCard['type'] );

This will make sure we remember first suit being played, now to use it modify 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 = self::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).

In .js file we need to add one more subscription and notification handler:
dojo.subscribe( 'newScores', this, "notif_newScores" );
in setupNotifications

and
notif_newScores : function(notif) {
// Update players' scores
for ( var player_id in notif.args.newScores) {
this.scoreCtrl[player_id].toValue(notif.args.newScores[player_id]);
}
},
somewhere after. this.scoreCtrl is pre-existing object that shows the scoring and this function will update score values per player from notification argument

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 = self::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) {
$sql = "UPDATE player SET player_score=player_score-$points WHERE player_id='$player_id'";
self::DbQuery($sql);
$heart_number = $player_to_points [$player_id];
self::notifyAllPlayers("points", clienttranslate('${player_name} gets ${nbr} hearts and looses ${nbr} points'), array (
'player_id' => $player_id,'player_name' => $players [$player_id] ['player_name'],
'nbr' => $heart_number ));
} else {
// No point lost (just notify)
self::notifyAllPlayers("points", clienttranslate('${player_name} did not get any hearts'), array (
'player_id' => $player_id,'player_name' => $players [$player_id] ['player_name'] ));
}
}
$newScores = self::getCollectionFromDb("SELECT player_id, player_score FROM player", true );
self::notifyAllPlayers( "newScores", '', array( 'newScores' => $newScores ) );

///// Test if this is the end of the game
foreach ( $newScores as $player_id => $score ) {
if ($score <= -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 playCard 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

[[Category:Studio]]

Tutorial hearts

2023-11-10T08:39:50Z

Xmakina: /* Layout and Graphics */ add direct link to github

{{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.
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 heartsYOURNAME_heartsYOURNAME.tpl, 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).

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

<b>Attention!!!</b> Very important note about reloading, if you don't remember this you may spent hours debugging. Browser caches .css files and 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. The full game can be found in your FTP home folder.

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

// 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.png''' 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>

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

== 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. Project hearts is mounted to your home directory on bga server.
<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]].

Edit .tpl to add some divs to represent player table and hand area

<pre>
<div id="myhand_wrap" class="whiteblock">
<h3>My Hand</h3>
<div id="myhand">
</div>
</div>
</pre>

If you refresh you should see now white area with My Hand title.

[[File:Heartsla-tpl2.png]]

Now lets add a card into the hand, just so you can feel it. Edit .tpl 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 edit CSS remember that you have to FORCE-reload page, i.e. Ctrl-F5, otherwise its cached.
<i>Same when you change existing graphics files</i>.

You should see this:

[[File:Heartsla-tpl3.png]]

Awesome! Now lets do the rest of layout.

There are few ways of how html could have been generated, you could have start with nothing and generate
all by java script. Or you could have started with complete game markup in html and make java script just hide and move pieces around. BGA framework provides also a third way which is mix of both plus template engine to generate HTML using php. So lets do that.

Change .tpl file to have this inside
<pre>
<div id="playertables">


<div class="playertable whiteblock playertable_{DIR}">
<div class="playertablename" style="color:#{PLAYER_COLOR}">
{PLAYER_NAME}
</div>
<div class="playertablecard" id="playertablecard_{PLAYER_ID}">
</div>
</div>


</div>

<div id="myhand_wrap" class="whiteblock">
<h3>{MY_HAND}</h3>
<div id="myhand">
</div>
</div>
</pre>

What we did is we added "block" player, it is marked up using html comments. {VAR} notation is used
to inject variables and
<pre>

inside

</pre>
effectively allows us to do template loops.

In .view.php insert this code after 'Place your code below' comment

<pre>
$template = self::getGameName() . "_" . self::getGameName();

$directions = array( 'S', 'W', 'N', 'E' );

// this will inflate our player block with actual players data
$this->page->begin_block($template, "player");
foreach ( $players as $player_id => $info ) {
$dir = array_shift($directions);
$this->page->insert_block("player", array ("PLAYER_ID" => $player_id,
"PLAYER_NAME" => $players [$player_id] ['player_name'],
"PLAYER_COLOR" => $players [$player_id] ['player_color'],
"DIR" => $dir ));
}
// this will make our My Hand text translatable
$this->tpl['MY_HAND'] = self::_("My hand");
</pre>

What it does is for each player we have it will replicate the html between  and  tags, substituting the variable denoted by {XXX}
with the values you provide. The DIR variable in this case we pulling from directions array (where array_shift will take first element and remove it from the array).

Reload. If everything went well you should see this:

[[File:Heartsla-tpl4.png]]

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

#playertables {
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 .css and 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 css and 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 hearts.js file:
<pre>
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/stock" /// <==== HERE
],
</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:
<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".

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>
onPlayerHandSelectionChanged: function() {
var items = this.playerHand.getSelectedItems();

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

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

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

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

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.

Next we finally get into .game.php class, 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.
<pre>
parent::__construct();
self::initGameStateLabels( array(
"currentHandType" => 10,
"trickColor" => 11,
"alreadyPlayedHearts" => 12,
) );

$this->cards = self::getNew( "module.common.deck" );
$this->cards->init( "card" );
</pre>

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>

At this point I would 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/e3a049257b592ff6167688d4d344f8a83d349b08]

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
self::setGameStateInitialValue( 'currentHandType', 0 );

// Set current trick color to zero (= no trick color)
self::setGameStateInitialValue( 'trickColor', 0 );

// Mark if we already played hearts during this hand
self::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 = array ();
foreach ( $this->colors as $color_id => $color ) {
// spade, heart, diamond, club
for ($value = 2; $value <= 14; $value ++) {
// 2, 3, 4, ... K, A
$cards [] = array ('type' => $color_id,'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 material.inc.php and this way it can be accessed from all .php files (and .js if you send it via getAllDatas()).
We will edit this file now by adding these lines

<pre>
$this->colors = array(
1 => array( 'name' => clienttranslate('spade'),
'nametr' => self::_('spade') ),
2 => array( 'name' => clienttranslate('heart'),
'nametr' => self::_('heart') ),
3 => array( 'name' => clienttranslate('club'),
'nametr' => self::_('club') ),
4 => array( 'name' => clienttranslate('diamond'),
'nametr' => self::_('diamond') )
);

$this->values_label = array(
2 =>'2',
3 => '3',
4 => '4',
5 => '5',
6 => '6',
7 => '7',
8 => '8',
9 => '9',
10 => '10',
11 => clienttranslate('J'),
12 => clienttranslate('Q'),
13 => clienttranslate('K'),
14 => clienttranslate('A')
);
</pre>

Where $this->colors will define Suit labels and $this->values_label will define value labels.
If you noticed, we have two of each label for suits. This is because sometimes we need translated values on the php
side and sometimes we don't. In this case '''nametr''' will return a translated value in php, which is only useful when you throw exceptions to show the right strings. If you pass a value to the client via notification you should always use untranslated strings, and the client will translate it. 'clienttranslate' marks the value for translation but does not actually change it for php. For more about this wonderful translation stuff see [[Translations]].

== 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
dojo.place(this.format_block('jstpl_cardontable', {
x : this.cardwidth * (value - 2),
y : this.cardheight * (color - 1),
player_id : player_id
}), 'playertablecard_' + 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 add a card template in the .tpl file
<pre>
// Javascript HTML templates

var jstpl_cardontable = '<div class="cardontable" id="cardontable_${player_id}" style="background-position:-${x}px -${y}px">\
</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. The technique to do that is to implement a Javascript template object defined in the .tpl file with some
parameters, which will basically create a "div" string (yes you could have used string concatenation but it would not be fancy).
Now dojo.place places it (the div) on top of a placeholder. 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 = self::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:
<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>
Note: this code is for testing we will replace it with server interaction after we test it.

Now if you force reload (because we changed .css before) 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/01d4e2f595fd14c2adcc97a957d21bb2766f78a8]

== State Machine ==

Now we need to create a game state machine. So the states are:

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

In addition players can exchange cards so we need two more states for that but we will skip it for now.

The state handling spread across 4 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

<pre>
$machinestates = array(

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

/// 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( "giveCards" ),
"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( "playCard" ),
"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 )
),

// Final state.
// Please do not modify.
99 => array(
"name" => "gameEnd",
"description" => clienttranslate("End of game"),
"type" => "manager",
"action" => "stGameEnd",
"args" => "argGameEnd"
)

);
</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 into API defined
by .action.php file. All functions in this file are API between client and server and have very simple
and repetitive structures. In this case there are only two actions player can do - play a card or pass cards to other player. So these 2 functions go into .action.php file, we will only define one now since we have not implemented card passing states yet:

<pre>
public function playCard() {
self::setAjaxMode();
$card_id = self::getArg("id", AT_posint, true);
$this->game->playCard($card_id);
self::ajaxResponse();
}
</pre>

Now 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 array ();
}
</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
<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 = self::loadPlayersBasicInfos();
foreach ( $players as $player_id => $player ) {
$cards = $this->cards->pickCards(13, 'deck', $player_id);
// Notify player about his cards
self::notifyPlayer($player_id, 'newHand', '', array ('cards' => $cards ));
}
self::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)
self::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 = self::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 = self::activeNextPlayer();
self::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
<pre>
function playCard($card_id) {
self::checkAction("playCard");
$player_id = self::getActivePlayerId();
throw new BgaUserException(self::_("Not implemented: ") . "$player_id plays $card_id");
}
</pre>
We won't implement it yet but throw an exception which we will see if interaction is working properly

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)

== 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 = 'playCard';
if (this.checkAction(action, true)) {
// Can play a card
var card_id = items[0].id;
this.ajaxcall("/" + this.game_name + "/" + this.game_name + "/" + action + ".html", {
id : card_id,
lock : true
}, this, function(result) {
}, function(is_error) {
});

this.playerHand.unselectAll();
} else if (this.checkAction('giveCards')) {
// 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 playCard($card_id) {
self::checkAction("playCard");
$player_id = self::getActivePlayerId();
$this->cards->moveCard($card_id, 'cardsontable', $player_id);
// XXX check rules here
$currentCard = $this->cards->getCard($card_id);
// And notify
self::notifyAllPlayers('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' => self::getActivePlayerName(),'value' => $currentCard ['type_arg'],
'value_displayed' => $this->values_label [$currentCard ['type_arg']],'color' => $currentCard ['type'],
'color_displayed' => $this->colors [$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');

dojo.subscribe('newHand', this, "notif_newHand");
dojo.subscribe('playCard', this, "notif_playCard");

},

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 = self::loadPlayersBasicInfos();
self::notifyAllPlayers( 'trickWin', clienttranslate('${player_name} wins the trick'), array(
'player_id' => $best_value_player_id,
'player_name' => $players[ $best_value_player_id ]['player_name']
) );
self::notifyAllPlayers( '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>
dojo.subscribe( 'trickWin', this, "notif_trickWin" );
this.notifqueue.setSynchronous( 'trickWin', 1000 );
dojo.subscribe( 'giveAllCardsToPlayer', this, "notif_giveAllCardsToPlayer" );
</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 playCard function and add this before notify functions
$currentTrickColor = self::getGameStateValue( 'trickColor' ) ;
if( $currentTrickColor == 0 )
self::setGameStateValue( 'trickColor', $currentCard['type'] );

This will make sure we remember first suit being played, now to use it modify 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 = self::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).

In .js file we need to add one more subscription and notification handler:
dojo.subscribe( 'newScores', this, "notif_newScores" );
in setupNotifications

and
notif_newScores : function(notif) {
// Update players' scores
for ( var player_id in notif.args.newScores) {
this.scoreCtrl[player_id].toValue(notif.args.newScores[player_id]);
}
},
somewhere after. this.scoreCtrl is pre-existing object that shows the scoring and this function will update score values per player from notification argument

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 = self::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) {
$sql = "UPDATE player SET player_score=player_score-$points WHERE player_id='$player_id'";
self::DbQuery($sql);
$heart_number = $player_to_points [$player_id];
self::notifyAllPlayers("points", clienttranslate('${player_name} gets ${nbr} hearts and looses ${nbr} points'), array (
'player_id' => $player_id,'player_name' => $players [$player_id] ['player_name'],
'nbr' => $heart_number ));
} else {
// No point lost (just notify)
self::notifyAllPlayers("points", clienttranslate('${player_name} did not get any hearts'), array (
'player_id' => $player_id,'player_name' => $players [$player_id] ['player_name'] ));
}
}
$newScores = self::getCollectionFromDb("SELECT player_id, player_score FROM player", true );
self::notifyAllPlayers( "newScores", '', array( 'newScores' => $newScores ) );

///// Test if this is the end of the game
foreach ( $newScores as $player_id => $score ) {
if ($score <= -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 playCard 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

[[Category:Studio]]

Tips eminentdomain

2023-08-14T18:50:31Z

Xmakina: /* Tips from the Pros */

== Base Game ==
Take the time to learn the Base Game before you add in the Escalation expansion.

Pick either Warfare of Colonise for taking control of planets, don't try to use both.

Use the Research Action to remove the cards you don't plan on using. If you ever discard a card at the end of your round, ask yourself if you even want it in your deck.

Survey early to find planets which complement each other.

Try to get 3 planets of the same kind and push for the level 3 technology (7 research icons). These technologies give you game breaking abilities.

Remember that the planets don't have the level 1 technology that should match with them (Fertile does not have Improved Colonise, Advanced does not have Advanced Research and Metallic does not have Advanced Warfare)

Planets with a Colony symbol are a permanent discount to all colonisation costs instead of an extra icon when the role is chosen.

Planets which increase hand size will give you a lot more options each turn.

Keep an eye on how many cards are left in each role; if you're ahead consider taking a less efficient role to finish the game faster.

== Escalation Expansion ==
Annex can really mess with colonisers.

You can buy research with fighters, destroyers and battlecruisers. If you Warfare, you can get game end tech without needing to lead Research roles.

Diverse Planets are now an option, especially with Oversight Committee consider pushing for one-of-each

== Tips from the Pros ==

=== SMoslim ===
This is a Victory Point game the main source of VP's are your roles. You are allowed only one necessary 0 VP role, the one when you get your first tech. Next you should always get points in your roles. The main method to do that is to go for survey each time you cannot get points otherwise, especially in the beginning. A lot of beginners waist time in getting multiple level 1 tech that is useless because it is not worth the role you pay for them. You can however get them if you are following, not leading.

A tip I learned from analysing the top player is at the very beginning of the game; if you have first turn and you choose the Survey role, do not use any of your Survey cards. Keep them so you can use them to follow your opponent's Survey role.

If you get an Advanced Planet with a Research symbol early, consider skipping getting a Level 1 tech and get your fourth Research symbol from exchanging Politics for Research. This should be especially true if the Advanced world only needs 3 colonies to Settle.

In Escalation, Warfare is a big risk/big reward strategy. Most top players avoid it because of the risk. Skilled players can mix Warfare and Colonize mid game, but a player needs very specific circumstances and skills to make this work, so I do no advise this strategy for beginners. I would only go for Warfare in Escalation if I start with a metallic planet, and I Survey'd a metallic planet that only needs 4 fighters to attack, and preferably with a warfare symbol.

Not all tech cards are created equal, some of them are really powerful and should always be picked if they're available. Pay attention to what the top players choose. As your experience grows, and you can start paying attention to what your opponent is going for, you may get a less optimal technology just to prevent your opponent from getting it, since it fits perfectly into their strategy.

The Eminent Domain community on BGA is small, so it might be subject to "group think". Once you have became a strong player, you need to start experimenting with different strategies. Pay attention to what other players do that is unusual. Even when I thought I was an expert, I learned a lot from weaker players that were using unusual strategies.

I see a lot of players getting stuck in low levels even though they played a lot of games. The main reason, I believe, is because they never change their playing style and always do what they are used to. I am now a master, and I still think about a few strategies in the opening phases of the game that I figured weren't that optimal. So, you need to always keep evolving. I also asked some top players about the different tech cards and their strategies, however they never used them. That's a big mistake since it limits your growth, and although those players are great, they hit the limit of the potential of their limited strategies.

The main reason is one of two; they play on auto mode so they don't get out of their confort zone. Or, they don't want to risk experimenting because losing comes at a great punishment, which I, personally, understand. The main solution to this is to play lots of Scenario games since they force new strategies on you while you are still a Good or Strong player since losing isn't that big of a deal that those levels. Now that I'm at a master ranking, losing any game absolutely destroys my ELO rating.

If you are really serious about the game, you need to start analysing high level player games and critique their decisions and compare them to yours. However, don't follow these games blindly, high level players aren't perfect, and also they don't always tale the game super seriously, and sometimes make a worse decision because it us more fun.

One of the most successful strategies that I use now is the Heavy Survey/Remove Cards opening strategy. I use this strategy because during a game, sometimes you get the perfect colonize hand but no Face Down planets, or more colonize cards than needed for the planets you have, so you are forced to play a suboptimal role. You never have this problem if you have an abundance of Face Down planets, so get a lot of planets in the early game so you can always have optimal turns and a lot of options to where you want to take the game according to your circumstance. When I first discovered this strategy, I quickly found it has a huge flaw, it fills your deck with Survey cards that are, generally, useless in the mid to late game. So, the Heavy Remove cards from the game strategy is needed as well. You need to keep removing those Survey cards from your deck, using the Research action, to keep your deck compact.

Another strategy that comes with this one. Is that you try to get at least one follow. Either by following Survey or Colonise. To that you need to keep your hand prepared for those. Following is main source of extra points in high level games. To have the ability to follow you need to keep cheking your opponents discard pile so you can predict their next move. To do that you might need, from time to time, to use the wait option before the clean up phase to see if your opponents follows you. Just don't be the guy that use it all the time, especially in turn based games. I encountered a few of those players and it just slows down the game a lot for no reason.

Deck balance: a lot of rookies and some times top players go for heavy warfare or heavy survey without paying attention to their deck balance. Although it seems perfect at the start, they later start getting a lot of cards they don't need, or take roles they dont want to take, and it only gets worse and removing cards frome your deck mid game is really suboptimal. So you need to avoid it. Unless you are using Oversight Commitee tech card, which is not as bad. Your deck needs to always be balanced so don't mess it up at the opening stage.

Discard pile: as previously said, pay attention to your opponents discard pile to predict if he is going to follow you or what is he going to play next turn.but another very important discard pile is the planets discard pile. When you became a strong player you should know all the planets of the game. so use the discard pile to predict what you might get. Although you cannot see the cards in the planets deck you can have perfect information just by looking at cards in colonies and the discard pile. Some times you give up on your perfect role just to play or follow a surveil role to get the top Planet because it is woth it for you or too good to let your opponent get it.

Bad tech cards are extremely powerful in some strategies: if you are going for a strategy double down on it in the tech cards have your entire deck go for it instead of having a diversified strat. It might seem simple as a tip but no very few players go for this because they are swayed buy the shiny good tech card. Because they are used to choosing it. Especially that this adviced cannot always be used to the fullest since it is a circumstances specific. The the real tip hiding behind this obvious one is always pay attention to your go-to moves yes they are the best in 90% of the times but not in 100% of them and this is way a lot of players never played some tech cards because they missed the opportunity to use them when the rare circumstance to use them optimally comes up.

Your action: most average to strong players don't understand how important this one is because roles are the source of points and the optimal action is most of the time obvious. But what they dont realise is that the action should be prepared. In the previous turn so you are not forced to an action.

One of the wosrt actions is the draw action it simply give you 0 point. It is only realy useful when you are in a race against your opponent to get a tech card first. Or to have a realy big role. But I a realy big one not to complete a normal one. Because when used to accomplish a big role it means

it made you play 2 roles in 1and that is not a common situation. By the way getting a lvl 3 tech card isn't a big role that is just a normal role. I mean by big a 1.5 to 2 roles in one. In other terms wining points. Another wast of an action is the remove cards from hand one once you are no longer in the opening phase.

So you only have as a good action the suttel/attack or a tech that doesn't what a role doses or win points. Otherwise you are wasting an action.

This tip however is top teir one don't pay attention to it if you are an average player because it needs high lvl hand management. Otherwise your action is foced any way.

Deck cycle:

Much more tips to come this just the generalities. I'm tired now. If you are a native English speaker you might need to rephrase an reorganize most of this. If you find a tip not clear or if you don't agree with it. Tell me so I clarify or have a discussion so we converge or agree to disagree

Tips eminentdomain

2023-05-30T18:53:09Z

Xmakina: Added tips from SMoslim

Tips eminentdomain

2023-05-30T11:02:09Z

Xmakina: Added some hints