Board Game Arena - User contributions [en]

Tools and tips of BGA Studio

2020-07-12T23:48:18Z

Brainchild: Moved lftp to the Linux sub-section of File Sync

{{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 "quit" icon on the top right of the screen.
* Click on "Express Stop".

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

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

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)

=== 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>http://en.studio.boardgamearena.com/#!table?table=12345</nowiki>

== Desktop and Web Tools ==
=== Code Editors and IDEs ===
==== 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

==== Visual Studio Code ====

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

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

==== 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 =====
<pre>
#!/bin/bash
BASEDIR=`dirname $0`
REMOTE=$BASEDIR/remote
LOCAL=$BASEDIR/workspace
GAME=mygamenamehere

#mount remote
fusermount -u $REMOTE #this unmounts dir
echo LongDevPassword | sshfs -o password_stdin 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

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

[https://lftp.yar.ru/ lftp] is a fast command-line file transfer program. It's a much better choice than rsync for BGA Studio since 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.

==== File Sync using VSCode ====
You might rely on your IDE to sync the files with the SFTP server. Each time you "save" a file with your modifications, the IDE will also submit it to the sFTP server. These are instructions for VS Code

* '''Install this extension''' https://marketplace.visualstudio.com/items?itemName=liximomo.sftp (File->Preferences->Extensions ... type SFTP and Install)

* '''Open VSCode on an empty folder''' that will be the local root of your project.

* Execute Ctrl+Shift+P on Windows/Linux or Cmd+Shift+P on Mac to open the command palette, and the type/run : '''"SFTP: config"''' - the edit will open with json config

* '''Update the json''' as below:

<pre>
{
"name": "BGA",
"host": "1.studio.boardgamearena.com",
"protocol": "sftp",
"port": 22,
"username": "<your SFTP username>",
"password": "<your SFTP password>",
"remotePath": "/<your project name>/",
"uploadOnSave": true,
"ignore": [
".vscode",
".git",
".DS_Store"
]
}
</pre>

- Execute Ctrl+Shift+P on Windows/Linux or Cmd+Shift+P on Mac to open the command palette, and the type/run : '''"SFTP: Download Project"'''.

This will download all the files locally, and each time you modify/save a file in VSCode, it will upload it to the SFTP Server.

=== Debuggers ===

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

=== Version Control ===
Studio providers svn for you code on server, there are some limited abilities there to see history and restore. I recommend to keep your code in another repository. I suggest to use git with local repo, which you can sync to cloud or backup.
Other option is to host source code on github, if you do use this convention github.com/<yourname>/bga-<yourgame>. In such case 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).

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

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/

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

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

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

Troubleshooting

2020-07-09T21:19:40Z

Brainchild:

{{Studio_Framework_Navigation}}

Describing common errors which is hard to understand and debug

== Game does not start at all ==

=== Undefined offset: 0 in table/table.game.php on line 830 ===

You are likely calling self::getActivePlayerName () during setupNewGame()

=== Unexpected error: Wrong formatted data from BGA gameserver 1 (method: createGame): ... ===

This is generic message usually followed by exact position in your source code, and usually its syntax error in one of yours php script

=== Unexpected error: Propagating error from GS 1 (method: createGame): Fatal error during yourgame setup: Not logged ===

Calling self::getCurrentPlayerId () or using $g_user from 'args' state function, see also below

=== Unexpected error: Propagating error from GS 1 (method: createGame): Fatal error during yourgame setup: Unknow player statistic: ===

Calling self::incStat() with second parameter which is an empty string

=== Unexpected error: Propagating error from GS 1 (method: createGame): Fatal error during yourgame setup: Error while processing SQL request: INSERT INTO stats ... ===

Fatal error during yourgame setup: Error while processing SQL request: INSERT INTO stats (stats_type, stats_player_id, stats_value) VALUES ('10','2300663','0'),('10','2300662','0')
Duplicate entry '10-2300663' for key 'stats_table_id'

Why? In the stats.inc.php you declared two keys with the same integer "id"

=== Fatal error during creation of database ebd_quoridor_389 Not logged ===

Check that you didn't use $g_user or getCurrentPlayerId() in setupNewGame() function or in an 'args' function of your state.

As these functions are not consequences of a user action, there is no current player defined.

As a general rule, you should use getActivePlayerId() and not getCurrentPlayerId(). See the [http://www.slideshare.net/boardgamearena/bga-studio-focus-on-bga-game-state-machine presentation on the game state machine] for more information.

=== Warning: Invalid argument supplied for foreach() in table.game.php ===

Warning: Invalid argument supplied for foreach() in /var/tournoi/release/tournoi-151226-1240-gs/www/game/module/table/table.game.php on line 129
Fatal error: Cannot unset string offsets in /var/tournoi/release/tournoi-151226-1240-gs/www/game/module/table/table.game.php on line 143

That appears when your arg* function that suppose to return array of state arguments returns a scalar (a non-array) value

=== The server reported an error ===

During table creation: "The server reported an error" error shown and nothing else.

If you cannot even create a table - there is syntax error in gameinfos.php, check it, reload it from management panel.
If still no luck copy clean version from template https://github.com/elaskavaia/bga-sharedcode/blob/master/gameinfos.inc.php

== Game starts but I can't make a move ==

=== When I do a move, I got "Move recorded, waiting for update ..." forever ===

"Move recorded" means that your ajaxcall request has been sent to the server and returned normally.

"Waiting for update" means that your client interface is waiting for some notifications from the server that correspond to the move we just did.

If this message stays forever, it is probably that your PHP code does not send any notification when the move happens, which is abnormal. To fix this: add a notifyAllPlayers or a notifyPlayer call in your PHP code.

=== When I do a move, I get "Sending move to server..." the nothing and game resets to state before the move ===

Its possible that server code get into infinite loops or thinks too much, in which case it will timeout and will be aborted without any extra logs (and any db transaction you saw in the log won't be committed). You will usually see "Unable to connect to server" message on console in this case. You have to put more logging into server
to trace where it hangs.

=== Some player action is triggered randomly when I click somewhere on the game area ===

You probably used "dojo.connect" on a null object. In this case, dojo.connect associate the event (ex: "onclick") to the whole game area.

Most of the time it happens in this situation, when my_object element does not exists:
<pre>
dojo.connect( $("my_object"), "onclick", this, function() {
...
}
</pre>

To determine if this is the case, place "alert( $("my_object") )" before the dojo.connect to check if the object exists or not.

=== "This is not your turn" error when I click on a possible move ===

You need to change to the active player by clicking the red arrow next to their name in the player panel (right side of the page).

[[File:Change_active_player.jpg]]

== Predefined server errors ==

=== Unexpected error: Unexpected final game state (XX) ===

The action function does not transition to any state, i.e.
function selectField($field) {
self::checkAction ( 'selectField' );
if ($field!=0) $this->gamestate->nextState ( 'next' );
}
Here if $field is 0 there is no transition

=== This game action is impossible right now ===

Check the game log. Usually your state does not define the action you trying to perform in 'possibeactions' array.

=== Unexpected error: This transition (playerTurn) is impossible at this state (42) ===

This is pretty self explanatory. Function nextState() takes transition name not a state name, so you probably did not
define this transition that the given state

== Game interface hangs during reload or on start ==

Showing "Application Loading..."

=== Javascript error: During pageload undefined no_stack_avail Script: ===

This error usually has no useful data, but it means you called somes API that require a callback and did not define callback function, i.e
in dojo.connect, this.connectClass, dojo.subscribe, etc

this.connectClass('field', 'onclick', 'onField'); // <-- onField is not defined

=== Other errors with "Application loading..." ===

You probably have a syntax error in your Javascript code, and the interface refuses to load.

To find this error, check if there is an error message in the Javascript console (F12).

If there is really nothing on the log, it's probably that the system was unable to load your Javascript because of an syntax error that affect the structure of the Javascript file, typically a missing "}" or a missing "," after a method definition.

If you have "Uncaught ReferenceError: bgagame is not defined" you have major syntax error in your js file, you should see some other clues in the log where the errors is.

=== Unexpected Syntax Error: ===

No further details in the log. When log is filling with some social connect errors.

Possible Reason: Syntax error in of the php script which is loaded before the start, such as gameoptions.inc.php, gameinfos.inc.php and such.

=== Game interface spins in a loop throwing error ===

Errors is something like "Cannot read property 'is_ai' of undefined". Cannot restart the game because cannot access UI to stop.
Likely you get in actplayer state with player id == 0. The only way to fix it is to edit database, globals index == 2 set player id to one of your test dudes
(can copy from row 5 for example).

== Type conversion / juggling errors ==

=== On php side I get a number instead of string I expect ===

$num = 3;
$meeple = "meeple_" + $num; // <-- suppose to be "meeple_3"!

When you switch between JS and PHP it easy to type this and not notice the +. Plus sign (+) in php does not mean string concatenation (in javascript does!),
in php + means integer arithmetic. So change + to . (dot)

=== On php side my string comparison does not work ===

if ($color == '4baae2' || $color == '000000') {
}

Apparently you should not be using '==' in php to compare strings! You should use '==='. The (==) operator will typecast the strings
to numbers then do comparison!
Its not very apparent because usually you can get away with it, but not when strings resemble numbers like hex 'colors'.

=== Integer columns in the database are returned as strings ===

This is normal PHP behavior. All fields are returned as string type, regardless of their actual type in the database. This also applies to global variables accessed via getGameStateValue(), since they are stored in a database table.

You can use type-casting to convert them to the correct type after they come out of the database.

$myValueInt = (int)self::getGameStateValue(GLOBAL_ROUND_NUMBER);

or

$sql = "SELECT my_int_column FROM my_table WHERE my_condition";
$myResult = self::getUniqueValueFromDB($sql); <-- this is a string
$myResultAsInt = (int)$myResult;

https://stackoverflow.com/questions/5323146/mysql-integer-field-is-returned-as-string-in-php

== Zombie mode ==

=== Unexpected error: Propagating error from GS 1 (method: zombie): Not logged ===

You are probably calling getCurrentPlayerId() or getCurrentPlayerName() in your zombieTurn method or any of the methods it uses. Instead, use the $active_player_id provided as parameter to zombieTurn().

=== Unexpected error: Can't manage zombie player in this game state ===

Despite what the message suggests, this error has nothing to do with your state machine. It is caused by an exception in the zombie code. It could be an undefined value sent to a database query. Check the unexpected exceptions log. It could also be the same problem as above, so look for getCurrentPlayerId() or getCurrentPlayerName() in your zombieTurn method.

=== Unexpected error: Wrong formatted data from BGA gameserver 1 (method: zombie): ===

This is almost certainly an undefined value in PHP code. Look for a warning or error message in the game replay log on the right side of the table UI.

=== Unexpected error: BGA gameserver 1 do not respond (method: zombie) (timeout: cluster) ===

You are trying to end the game from a zombie method. This is not allowed. The zombie logic must continue the game as best it can. See [[Main_game_logic:_yourgamename.game.php#Zombie_mode|Zombie mode]] for more info.

== Other errors ==

=== Javascript does not know how to sum two numbers ===

Be careful when you manipulate integers returned by notifications: most of the time, Javascript considers they are Strings and not Integers.

As a result:
<pre>
var i=1;
i += notif.args.increment; // With notif.args.increment='1'
alert( i ); // i=11 instead of 2 !! Javascript concatenate 2 strings !
</pre>

To solve this, you should use the "toint" function:
<pre>
var i=1;
i += toint( notif.args.increment ); // With notif.args.increment='1'
alert( i ); // i=2 :)
</pre>

=== Javascript: do not use substr with negative numbers ===

To get the last characters of a string, use "slice" instead of "substr" which has a bug on IE:
<pre>
var three_last_characters = string.substr( -3 ); // Wrong
var three_last_characters = string.slice( -3 ); // Correct
</pre>

=== Game "spontaneously" transition to a new state without user input ===

Make sure on php side you have no code after $this->gamestate->nextState(...) code.
Because if you do accidentally have code that goes to another state it will cause another state transition without user interaction.

function selectField($field) {
self::checkAction ( 'selectField' );
if ($field!=0) $this->gamestate->nextState ( 'next' );
$this->gamestate->nextState ( 'last' ); // <-- here is missing else, so it will cause double state transition
}

First steps with BGA Studio

2020-07-09T21:05:48Z

Brainchild: Added a note about changing to another test account using the red arrow since many new developers are confused by this (myself included)

{{Studio_Framework_Navigation}}

== Connect to the BGA Studio website ==

Go to BGA Studio website:
http://en.studio.boardgamearena.com

Choose one of your 10 accounts (ex: myusername0), and login into the website - as you would do for Board Game Arena.

If you don't have account see [[How to join BGA developer team?]]

== Create a new game project ==

You can do most of the projects-related operations from "Control Panel / Manage games". In particular, you can create a new project automatically from there.

Your first "game" should be one of the tutorials, so your project name should be something like "tutorialbob".

At this stage it is too early to create a real game but if you really don't want to start until you have a game in mind, check [[Create a game in BGA Studio: Complete Walkthrough]]
section "Select a First Game"

For reference top bar studio links
* AVAILABLE LICENSES - list of all available licenses (not public domain) - http://en.studio.boardgamearena.com/#!licensing
* STUDIO PROJECTS - list of all registered studio projects - http://en.studio.boardgamearena.com/#!projects
* CONTROL PANEL - manage projects - http://en.studio.boardgamearena.com/#!controlpanel

== Connect to your SFTP folder ==

From the initial email from the Studio you get:
* the name of the SFTP server to connect to
* your SFTP login and password

Using this information:
# Connect to the SFTP server using your SFTP login and password, through your favourite SFTP client software (such as [http://winscp.net/ WinSCP], see [[Tools_and_tips_of_BGA_Studio#File_Sync_on_Windows|File Sync]])
# Check that your remote home folder contains one folder for each of the three example games (reversi, hearts, gomoku). If you have already created a new game project, one additional folder should be in your "home" folder.
# Note: You have to setup AUTOMATED sync between your folder and remote folder, manually ftp'ing files would be no-starter. For WinSCP you can do this from the file menu (Commands->Keep remote directories up to Date...)

== Let's code! ==

Now, you can try to launch a new game on BGA Studio from the "Play now" menu entry, as you would do on Board Game Arena website.

# Find your game in the 'PLAY NOW' section and create a table
# Use the 'I want between X and X' players to tick down the maximum players number to the minimum
# Click 'Express start': your game launches with the maximum number of players specified. It shows an empty canvas: in the game zone you just have a sentence 'This is your game interface. You can edit this HTML in your ".tpl" file.'.
# Switch to your SFTP home folder, go into your game folder. Edit the game_game.tpl file, and change this sentence to 'Hey, this is my first game!', then save.
# Go back to your browser and refresh, check that the game zone has updated.
# Click the red arrow next to a test account's name in the player panel to view the game from that player's account <br/>[[File:Change_active_player.jpg]]
# Click on the 'Gear' icon on the top right, and in the popup choose 'Express STOP'. The game ends automatically and you are brought back to the table screen for this ended game.
# Switch to your game folder, go into the img folder and overwrite your game_box.png file with another image.
# Go back to your browser, '''empty your browser cache''', then refresh the page, and check that the game box image has been updated.

Then you can modify the provided skeleton and begin to develop your game :)

== Commit your changes ==

Committing uploads your changes on BGA's [http://en.wikipedia.org/wiki/Revision_control revision control] system. This is an extra assurance not to lose your code, and to have the possibility to get a previous version of your code if you need to backtrack. It also helps us to follow your progress (we get an email when you commit). So you should commit from time to time, when you hit some landmark in your development.

You can automatically commit your sources in the repository from "Control Panel / Manage Games / Your game / Commit my modifications now". Then:

# Enter your commit comment (such as 'My first commit') then hit the 'Submit' button;
# Check the log for errors, it should end with the following lines:

Transmitting file data .
Committed revision #revision number#.
HAL says: done.

NOTE: committing the code is currently not working until admin commits it manually the first time. Even if it does you cannot automatically deal with this version control system except for committing. Therefore its recommended to use another means of storing the code in version control system, such as local git repo or github, see [[Tools_and_tips_of_BGA_Studio#Version_Control|Version Control]]

== That's all! ==

Now you know about the basics of updating your game on BGA Studio and testing your changes.

Now you can select one of the tutorials to play with and start coding.

For links to tutorials and ALL studio documentation see [[Studio]].

File:Change active player.jpg

2020-07-09T20:59:17Z

Brainchild: Shows how to change to a test account if the current player is not the active one

== Summary ==
Shows how to change to a test account if the current player is not the active one

Troubleshooting

2020-07-09T20:44:12Z

Brainchild: Added instructions for changing to the next test player in a multiplayer game

{{Studio_Framework_Navigation}}

Describing common errors which is hard to understand and debug

== Game does not start at all ==

=== Undefined offset: 0 in table/table.game.php on line 830 ===

You are likely calling self::getActivePlayerName () during setupNewGame()

=== Unexpected error: Wrong formatted data from BGA gameserver 1 (method: createGame): ... ===

This is generic message usually followed by exact position in your source code, and usually its syntax error in one of yours php script

=== Unexpected error: Propagating error from GS 1 (method: createGame): Fatal error during yourgame setup: Not logged ===

Calling self::getCurrentPlayerId () or using $g_user from 'args' state function, see also below

=== Unexpected error: Propagating error from GS 1 (method: createGame): Fatal error during yourgame setup: Unknow player statistic: ===

Calling self::incStat() with second parameter which is an empty string

=== Unexpected error: Propagating error from GS 1 (method: createGame): Fatal error during yourgame setup: Error while processing SQL request: INSERT INTO stats ... ===

Fatal error during yourgame setup: Error while processing SQL request: INSERT INTO stats (stats_type, stats_player_id, stats_value) VALUES ('10','2300663','0'),('10','2300662','0')
Duplicate entry '10-2300663' for key 'stats_table_id'

Why? In the stats.inc.php you declared two keys with the same integer "id"

=== Fatal error during creation of database ebd_quoridor_389 Not logged ===

Check that you didn't use $g_user or getCurrentPlayerId() in setupNewGame() function or in an 'args' function of your state.

As these functions are not consequences of a user action, there is no current player defined.

As a general rule, you should use getActivePlayerId() and not getCurrentPlayerId(). See the [http://www.slideshare.net/boardgamearena/bga-studio-focus-on-bga-game-state-machine presentation on the game state machine] for more information.

=== Warning: Invalid argument supplied for foreach() in table.game.php ===

Warning: Invalid argument supplied for foreach() in /var/tournoi/release/tournoi-151226-1240-gs/www/game/module/table/table.game.php on line 129
Fatal error: Cannot unset string offsets in /var/tournoi/release/tournoi-151226-1240-gs/www/game/module/table/table.game.php on line 143

That appears when your arg* function that suppose to return array of state arguments returns a scalar (a non-array) value

=== The server reported an error ===

During table creation: "The server reported an error" error shown and nothing else.

If you cannot even create a table - there is syntax error in gameinfos.php, check it, reload it from management panel.
If still no luck copy clean version from template https://github.com/elaskavaia/bga-sharedcode/blob/master/gameinfos.inc.php

== Game starts but I can't make a move ==

=== When I do a move, I got "Move recorded, waiting for update ..." forever ===

"Move recorded" means that your ajaxcall request has been sent to the server and returned normally.

"Waiting for update" means that your client interface is waiting for some notifications from the server that correspond to the move we just did.

If this message stays forever, it is probably that your PHP code does not send any notification when the move happens, which is abnormal. To fix this: add a notifyAllPlayers or a notifyPlayer call in your PHP code.

=== When I do a move, I get "Sending move to server..." the nothing and game resets to state before the move ===

Its possible that server code get into infinite loops or thinks too much, in which case it will timeout and will be aborted without any extra logs (and any db transaction you saw in the log won't be committed). You will usually see "Unable to connect to server" message on console in this case. You have to put more logging into server
to trace where it hangs.

=== Some player action is triggered randomly when I click somewhere on the game area ===

You probably used "dojo.connect" on a null object. In this case, dojo.connect associate the event (ex: "onclick") to the whole game area.

Most of the time it happens in this situation, when my_object element does not exists:
<pre>
dojo.connect( $("my_object"), "onclick", this, function() {
...
}
</pre>

To determine if this is the case, place "alert( $("my_object") )" before the dojo.connect to check if the object exists or not.

=== "This is not your turn" error when I click on a possible move ===

You need to change to the active player by clicking the red arrow next to their name in the player panel (right side of the page).

== Predefined server errors ==

=== Unexpected error: Unexpected final game state (XX) ===

The action function does not transition to any state, i.e.
function selectField($field) {
self::checkAction ( 'selectField' );
if ($field!=0) $this->gamestate->nextState ( 'next' );
}
Here if $field is 0 there is no transition

=== This game action is impossible right now ===

Check the game log. Usually your state does not define the action you trying to perform in 'possibeactions' array.

=== Unexpected error: This transition (playerTurn) is impossible at this state (42) ===

This is pretty self explanatory. Function nextState() takes transition name not a state name, so you probably did not
define this transition that the given state

== Game interface hangs during reload or on start ==

Showing "Application Loading..."

=== Javascript error: During pageload undefined no_stack_avail Script: ===

This error usually has no useful data, but it means you called somes API that require a callback and did not define callback function, i.e
in dojo.connect, this.connectClass, dojo.subscribe, etc

this.connectClass('field', 'onclick', 'onField'); // <-- onField is not defined

=== Other errors with "Application loading..." ===

You probably have a syntax error in your Javascript code, and the interface refuses to load.

To find this error, check if there is an error message in the Javascript console (F12).

If there is really nothing on the log, it's probably that the system was unable to load your Javascript because of an syntax error that affect the structure of the Javascript file, typically a missing "}" or a missing "," after a method definition.

If you have "Uncaught ReferenceError: bgagame is not defined" you have major syntax error in your js file, you should see some other clues in the log where the errors is.

=== Unexpected Syntax Error: ===

No further details in the log. When log is filling with some social connect errors.

Possible Reason: Syntax error in of the php script which is loaded before the start, such as gameoptions.inc.php, gameinfos.inc.php and such.

=== Game interface spins in a loop throwing error ===

Errors is something like "Cannot read property 'is_ai' of undefined". Cannot restart the game because cannot access UI to stop.
Likely you get in actplayer state with player id == 0. The only way to fix it is to edit database, globals index == 2 set player id to one of your test dudes
(can copy from row 5 for example).

== Type conversion / juggling errors ==

=== On php side I get a number instead of string I expect ===

$num = 3;
$meeple = "meeple_" + $num; // <-- suppose to be "meeple_3"!

When you switch between JS and PHP it easy to type this and not notice the +. Plus sign (+) in php does not mean string concatenation (in javascript does!),
in php + means integer arithmetic. So change + to . (dot)

=== On php side my string comparison does not work ===

if ($color == '4baae2' || $color == '000000') {
}

Apparently you should not be using '==' in php to compare strings! You should use '==='. The (==) operator will typecast the strings
to numbers then do comparison!
Its not very apparent because usually you can get away with it, but not when strings resemble numbers like hex 'colors'.

=== Integer columns in the database are returned as strings ===

This is normal PHP behavior. All fields are returned as string type, regardless of their actual type in the database. This also applies to global variables accessed via getGameStateValue(), since they are stored in a database table.

You can use type-casting to convert them to the correct type after they come out of the database.

$myValueInt = (int)self::getGameStateValue(GLOBAL_ROUND_NUMBER);

or

$sql = "SELECT my_int_column FROM my_table WHERE my_condition";
$myResult = self::getUniqueValueFromDB($sql); <-- this is a string
$myResultAsInt = (int)$myResult;

https://stackoverflow.com/questions/5323146/mysql-integer-field-is-returned-as-string-in-php

== Zombie mode ==

=== Unexpected error: Propagating error from GS 1 (method: zombie): Not logged ===

You are probably calling getCurrentPlayerId() or getCurrentPlayerName() in your zombieTurn method or any of the methods it uses. Instead, use the $active_player_id provided as parameter to zombieTurn().

=== Unexpected error: Can't manage zombie player in this game state ===

Despite what the message suggests, this error has nothing to do with your state machine. It is caused by an exception in the zombie code. It could be an undefined value sent to a database query. Check the unexpected exceptions log. It could also be the same problem as above, so look for getCurrentPlayerId() or getCurrentPlayerName() in your zombieTurn method.

=== Unexpected error: Wrong formatted data from BGA gameserver 1 (method: zombie): ===

This is almost certainly an undefined value in PHP code. Look for a warning or error message in the game replay log on the right side of the table UI.

=== Unexpected error: BGA gameserver 1 do not respond (method: zombie) (timeout: cluster) ===

You are trying to end the game from a zombie method. This is not allowed. The zombie logic must continue the game as best it can. See [[Main_game_logic:_yourgamename.game.php#Zombie_mode|Zombie mode]] for more info.

== Other errors ==

=== Javascript does not know how to sum two numbers ===

Be careful when you manipulate integers returned by notifications: most of the time, Javascript considers they are Strings and not Integers.

As a result:
<pre>
var i=1;
i += notif.args.increment; // With notif.args.increment='1'
alert( i ); // i=11 instead of 2 !! Javascript concatenate 2 strings !
</pre>

To solve this, you should use the "toint" function:
<pre>
var i=1;
i += toint( notif.args.increment ); // With notif.args.increment='1'
alert( i ); // i=2 :)
</pre>

=== Javascript: do not use substr with negative numbers ===

To get the last characters of a string, use "slice" instead of "substr" which has a bug on IE:
<pre>
var three_last_characters = string.substr( -3 ); // Wrong
var three_last_characters = string.slice( -3 ); // Correct
</pre>

=== Game "spontaneously" transition to a new state without user input ===

Make sure on php side you have no code after $this->gamestate->nextState(...) code.
Because if you do accidentally have code that goes to another state it will cause another state transition without user interaction.

function selectField($field) {
self::checkAction ( 'selectField' );
if ($field!=0) $this->gamestate->nextState ( 'next' );
$this->gamestate->nextState ( 'last' ); // <-- here is missing else, so it will cause double state transition
}

Post-release phase

2020-07-08T21:18:42Z

Brainchild: Fixed the link to the bugs forum

{{Studio_Framework_Navigation}}

Your game is now on BGA: congrats!

But what happened when there are some bugs to fix or when you want to optimize something?

Don't be afraid: you're still allowed to modify your game. You just have to pay attention to the points below.

== Bugs reporting ==

Bugs are reported on the [https://boardgamearena.com/bugs BGA bugs page].

During days after your game has been published and from time to time, please have a look at it to check if everything is fine.

== How to submit changes? ==

There is 3 (short) steps to make your changes visible on BGA (from your Control Panel):

* Commit your changes.
* Build a new version (don't forget to do a successful commit BEFORE your build).
* Deploy your new version in production.

== What can be modified after release? ==

Everything can be modified. BUT, some items requires a special attention, and you must inform us in some cases:

===Changes that breaks the games in progress===

Some changes will break the games in progress at the moment the release/the hotfix will be performed. Each time you make a change, you should ask you the question "it is safe to make this change in a game in progress", and if the answer is "no" you have to inform us.

Example of changes that break the games in progress:
* Changes in the database schema of the game (dbmodel.sql).
* New global variable or game option accessed during the game (if it's only used during setup, it should be safe).
* Change ID of existing game states (adding new game states is fine).

Of course, as a rule of thumb, you should avoid to introduce changes that break a game in progress. Sometimes however, you do not have any other choice. In this case:
* Try to group all your updates in one version, thus we won't have to block your game several times.
* Tell us explicitly that you introduce some update that can break games in progress so we can block the game during a short time.

Note: in the near future, we will introduce the possibility for you to block/unblock a game directly from your Control Panel in order to perform all the process by yourself.

=== Updating game options ===

* If you add options, you should let us know which value should be used for the arena mode, so that we can update the arena configuration.
* If you remove an option or change a version ID, it will break the arena configuration and prevent creating new arena games, so you should let us know so that we can synchronize to update the configuration at the same time as you deploy the new version.
* Do not change option IDs once the game is in production, it will break ongoing games and audience option statistics.

=== Updating Statistics ===

You should be careful when updating a statistics:

* If you want to add a new statistic, please be aware that for ongoing games this statistic won't always be correct since it has not been counted from the start of that game.
* If you want to update a statistic, please update it and do not remove/create another one. Otherwise, the statistic won't keep the same ID and players will lose all the historical statistics data.
* If your game is published on BGA, please don't remove any statistics (historical data will be lost).

=== Updating the database schema ===

If you want to update the database schema of the game (dbmodel.sql) and your game is already open to everyone on BGA (from BETA onwards), you should inform us before releasing the new version (see "[[#Changes that breaks the games in progress|changes that breaks the games in progress]]").

Any modification in dbmodel.sql should also appear in your nameofyourgame.game.php, in a function

function upgradeTableDb( $from_version ){

if( $from_version <= YYMMDDHHMM ){ // where your CURRENT version in production has number YYMMDD-HHMM

// You DB schema update request.
// Note: all tables names should be prefixed by "DBPREFIX_" to be compatible with the applyDbUpgradeToAllDB method you should use below
$sql = "CREATE TABLE DBPREFIX_xxxxxxx ....";

// The method below is applying your DB schema update request to all tables, including the BGA framework utility tables like "zz_replayXXXX" or "zz_savepointXXXX".
// You should really use this request, in conjunction with "DBPREFIX_" in your $sql, so ALL tables are updated. All utility tables MUST have the same schema than the main table, otherwise the game may be blocked.
self::applyDbUpgradeToAllDB( $sql );

}}

Note1: of course you need to change your dbmodel.sql accordingly, so that new games get your updated scheme.

Note2: this is always risky to modify the DB scheme, so:
* if your game is already open to everyone on BGA (from BETA onwards), it may be worth contacting us before, so we can stop the realtime games during the update (this way, only turn based games are concerned by the DB live upgrade).
* if you can avoid it... try to avoid it :)

Note3: testing on the studio is possible by following the following procedure:
* make sure the current state of your project is correctly committed
* revert to the revision currently in production using the version control tools ("Display commit log" -> find the revision matching the current version in production, then "Overwrite working copy with this revision" to get back the matching code)
* launch a game with this code
* revert to your code latest version using the version control tools (use "Overwrite working copy with this revision" with "head" for the revision)
* access the game database
* in the "global" table, find the row with id 300. Its value is 999999999 by default on the studio. Change it to the current production version number
* hit refresh to reload your game page. Your upgradeTableDb() function will be run and the global value will be updated again to the studio value
* check the database to see if your changes have been correctly applied.

=== Updating string to be translated ===

When you update a string that has been marked to be translatable, please keep in mind that all current translations done by the BGA community will be lost.

Consequently, when you are about to modify a string to be translated (after release), please ask you the following questions:
* Is it just an English misspelling? In this case, it is better to fix the English translation of the string than the original string to be translated.
* Has the meaning of the string changed? If yes, you HAVE to change the original string in order to invalidate all translations that has been done already.
* Is there a similar string already used elsewhere in my game? In this case, you'd better use it again to enjoy immediately all translations already available.

===Tell the community about your changes :)===

The player's community is always happy to know that someone is taking care of their preferred game :)

If your are the developer of game XXXX, you are also the administrator of player's group "XXXX's players", and you can publish some news in this group newsfeed.

When you fix a bug or add something, do not hesitate to tell the players about this in this group: you'll get the "thank you" you deserved :)

See for example Werewolves group:
https://boardgamearena.com/group?id=2465913

===Major changes===

If you do some major changes to your game like:
* Introducing a new expansion.
* Major code rewriting/refactoring.

... please tell us. In this case, we can:
* Make your game back from "gold" to "public beta", to incite player to report bugs.
* And eventually, publish a news about it :)

BGA Code Sharing

2020-07-07T19:56:30Z

Brainchild: Added A Fistful Of Gold to the list of projects

{{Studio_Framework_Navigation}}

This page is for listing of externally hosted bga projects, tools and resources, as well as internal project
intended for sharing

== Projects hosted not in studio ==

See the table a link and nickname of the developer on bga (same as used for dev forum), and short description

'''Important notice about artwork on BGA Open Source projects: original hi-resolution images from publishers must not be published on the repositories. In addition, it is better to specify that the images derivated from publishers artwork are copyrighted and cannot be licensed under a free license like Creative Commons.
'''

{| class="wikitable"
|-
! NON-GAME PROJECTS
! CODE LINK
! DEVELOPER
|-
| Shared Code (not a game)
| https://github.com/elaskavaia/bga-sharedcode
| Victoria_La
|-
| BoardGameArena Workbench (not a game)
| https://github.com/danielholmes/bga-workbench
| Daniel Holmes (dhau)
|-
! GAME
! CODE LINK
! DEVELOPER
|-
| Assyria
| https://github.com/sebastien-prudhomme/bga-assyria
| daikinee
|-
| Bandido
| https://github.com/opheliehb/BandidoBGA
| ophelopede & Harkle
|-
| The Battle for Hill 218
| https://github.com/danielholmes/battle-for-hill-218
| Daniel Holmes (dhau)
|-
| Bonbons
| https://github.com/AntonioSoler/bga-bonbons
| Morgalad
|-
| Coinche
| https://github.com/drasill/bga-coinche
| Draasill
|-
| Coup: City State
| https://github.com/quietmint/bga-coupcitystate
| quietmint
|-
| Egyptian Ratscrew
| https://github.com/0BuRner/bga-egyptianratscrew
| 0BuRner
|-
| Eruption
| https://github.com/AndyKerrison/bga-eruption
| Andy_K
|-
| A Fistful Of Gold
| https://bitbucket.org/Joel_L/fistfulofgold
| Brainchild
|-
| Florenza: The Card Game
| https://github.com/alberto-bottarini/bga-florenza
| tarini
|-
| Hearts '''(Tutorial)'''
| https://github.com/elaskavaia/bga-heartsla
| Victoria_La
|-
| Incan Gold
| https://github.com/AntonioSoler/bga-incangold
| Morgalad
|-
| Marco Polo
| https://github.com/rcitaliano/MarcoPolo
| rcitaliano
|-
| Nile
| https://github.com/AndyKerrison/bga-nile
| Andy_K
|-
| Noir: Killer vs Inspector
| https://bitbucket.org/chhuang76/bga_noirkvi
| ch huang
|-
| Penny Press
| https://github.com/AdamNovotny/bga-blooms
| A-dam
|-
| P.I.
| https://gitlab.com/fa81/bga-pi, https://github.com/hellp/bga-pi (mirror)
| Fabian Neumann (fa81)
|-
| Tablut
| https://github.com/Lucas-C/tablut
| Lucas-C & ntaffore
|-
| Takara Island
| https://github.com/AntonioSoler/bga-takaraisland
| Morgalad
|-
| Teotihuacan: City of Gods
| https://github.com/Trompetenhut/bga-teotihuacan
| Trompetenhut
|-
| The King's Guild
| https://github.com/AdamNovotny/BGG-KingsGuild
| A-dam
|}

== Projects on studio ==

Links to studio project which owner wish share as read only.
Project owner please add you project here, dev nickname and short description if you would like to share it.
For the projects below any developer can add themselves to a project as read-only from http://en.studio.boardgamearena.com/#!projects page.

{| class="wikitable"
|-
! NAME
! CODE LINK
! DEVELOPER
|-
| Shared Code
| http://en.studio.boardgamearena.com/#!studiogame?game=sharedcode
| Victoria_La
|-
| Original BGA template
| http://en.studio.boardgamearena.com/#!studiogame?game=template
| Victoria_La
|-
|}

== Other useful resources ==

* Archive of tutorial projects https://www.dropbox.com/s/rsd5r4v49xudpp0/Studio.zip?dl=0
** Note: Hearts project is corrupted there, use Hearts tutorial project above
* 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/
* BoardGameArena Workbench - set of tools to help test and deploy BGA projects - https://github.com/danielholmes/bga-workbench

Post-release phase

2020-07-06T16:37:57Z

Brainchild: /* Updating game options */

{{Studio_Framework_Navigation}}

Your game is now on BGA: congrats!

But what happened when there are some bugs to fix or when you want to optimize something?

Don't be afraid: you're still allowed to modify your game. You just have to pay attention to the points below.

== Bugs reporting ==

Bugs are reported in the [http://forum.boardgamearena.com/viewforum.php?f=4 BGA bugs forum].

During days after your game has been published and from time to time, please have a look at it to check if everything is fine.

== How to submit changes? ==

There is 3 (short) steps to make your changes visible on BGA (from your Control Panel):

* Commit your changes.
* Build a new version (don't forget to do a successful commit BEFORE your build).
* Deploy your new version in production.

== What can be modified after release? ==

Everything can be modified. BUT, some items requires a special attention, and you must inform us in some cases:

===Changes that breaks the games in progress===

Some changes will break the games in progress at the moment the release/the hotfix will be performed. Each time you make a change, you should ask you the question "it is safe to make this change in a game in progress", and if the answer is "no" you have to inform us.

Example of changes that break the games in progress:
* Changes in the database schema of the game (dbmodel.sql).
* New global variable or game option accessed during the game (if it's only used during setup, it should be safe).
* Change ID of existing game states (adding new game states is fine).

Of course, as a rule of thumb, you should avoid to introduce changes that break a game in progress. Sometimes however, you do not have any other choice. In this case:
* Try to group all your updates in one version, thus we won't have to block your game several times.
* Tell us explicitly that you introduce some update that can break games in progress so we can block the game during a short time.

Note: in the near future, we will introduce the possibility for you to block/unblock a game directly from your Control Panel in order to perform all the process by yourself.

=== Updating game options ===

* If you add options, you should let us know which value should be used for the arena mode, so that we can update the arena configuration.
* If you remove an option or change a version ID, it will break the arena configuration and prevent creating new arena games, so you should let us know so that we can synchronize to update the configuration at the same time as you deploy the new version.
* Do not change option IDs once the game is in production, it will break ongoing games and audience option statistics.

=== Updating Statistics ===

You should be careful when updating a statistics:

* If you want to add a new statistic, please be aware that for ongoing games this statistic won't always be correct since it has not been counted from the start of that game.
* If you want to update a statistic, please update it and do not remove/create another one. Otherwise, the statistic won't keep the same ID and players will lose all the historical statistics data.
* If your game is published on BGA, please don't remove any statistics (historical data will be lost).

=== Updating the database schema ===

If you want to update the database schema of the game (dbmodel.sql) and your game is already open to everyone on BGA (from BETA onwards), you should inform us before releasing the new version (see "[[#Changes that breaks the games in progress|changes that breaks the games in progress]]").

Any modification in dbmodel.sql should also appear in your nameofyourgame.game.php, in a function

function upgradeTableDb( $from_version ){

if( $from_version <= YYMMDDHHMM ){ // where your CURRENT version in production has number YYMMDD-HHMM

// You DB schema update request.
// Note: all tables names should be prefixed by "DBPREFIX_" to be compatible with the applyDbUpgradeToAllDB method you should use below
$sql = "CREATE TABLE DBPREFIX_xxxxxxx ....";

// The method below is applying your DB schema update request to all tables, including the BGA framework utility tables like "zz_replayXXXX" or "zz_savepointXXXX".
// You should really use this request, in conjunction with "DBPREFIX_" in your $sql, so ALL tables are updated. All utility tables MUST have the same schema than the main table, otherwise the game may be blocked.
self::applyDbUpgradeToAllDB( $sql );

}}

Note1: of course you need to change your dbmodel.sql accordingly, so that new games get your updated scheme.

Note2: this is always risky to modify the DB scheme, so:
* if your game is already open to everyone on BGA (from BETA onwards), it may be worth contacting us before, so we can stop the realtime games during the update (this way, only turn based games are concerned by the DB live upgrade).
* if you can avoid it... try to avoid it :)

Note3: testing on the studio is possible by following the following procedure:
* make sure the current state of your project is correctly committed
* revert to the revision currently in production using the version control tools ("Display commit log" -> find the revision matching the current version in production, then "Overwrite working copy with this revision" to get back the matching code)
* launch a game with this code
* revert to your code latest version using the version control tools (use "Overwrite working copy with this revision" with "head" for the revision)
* access the game database
* in the "global" table, find the row with id 300. Its value is 999999999 by default on the studio. Change it to the current production version number
* hit refresh to reload your game page. Your upgradeTableDb() function will be run and the global value will be updated again to the studio value
* check the database to see if your changes have been correctly applied.

=== Updating string to be translated ===

When you update a string that has been marked to be translatable, please keep in mind that all current translations done by the BGA community will be lost.

Consequently, when you are about to modify a string to be translated (after release), please ask you the following questions:
* Is it just an English misspelling? In this case, it is better to fix the English translation of the string than the original string to be translated.
* Has the meaning of the string changed? If yes, you HAVE to change the original string in order to invalidate all translations that has been done already.
* Is there a similar string already used elsewhere in my game? In this case, you'd better use it again to enjoy immediately all translations already available.

===Tell the community about your changes :)===

The player's community is always happy to know that someone is taking care of their preferred game :)

If your are the developer of game XXXX, you are also the administrator of player's group "XXXX's players", and you can publish some news in this group newsfeed.

When you fix a bug or add something, do not hesitate to tell the players about this in this group: you'll get the "thank you" you deserved :)

See for example Werewolves group:
https://boardgamearena.com/group?id=2465913

===Major changes===

If you do some major changes to your game like:
* Introducing a new expansion.
* Major code rewriting/refactoring.

... please tell us. In this case, we can:
* Make your game back from "gold" to "public beta", to incite player to report bugs.
* And eventually, publish a news about it :)

Troubleshooting

2020-07-04T10:27:32Z

Brainchild:

{{Studio_Framework_Navigation}}

Describing common errors which is hard to understand and debug

== Game does not start at all ==

=== Undefined offset: 0 in table/table.game.php on line 830 ===

You are likely calling self::getActivePlayerName () during setupNewGame()

=== Unexpected error: Wrong formatted data from BGA gameserver 1 (method: createGame): ... ===

This is generic message usually followed by exact position in your source code, and usually its syntax error in one of yours php script

=== Unexpected error: Propagating error from GS 1 (method: createGame): Fatal error during yourgame setup: Not logged ===

Calling self::getCurrentPlayerId () or using $g_user from 'args' state function, see also below

=== Unexpected error: Propagating error from GS 1 (method: createGame): Fatal error during yourgame setup: Unknow player statistic: ===

Calling self::incStat() with second parameter which is an empty string

=== Unexpected error: Propagating error from GS 1 (method: createGame): Fatal error during yourgame setup: Error while processing SQL request: INSERT INTO stats ... ===

Fatal error during yourgame setup: Error while processing SQL request: INSERT INTO stats (stats_type, stats_player_id, stats_value) VALUES ('10','2300663','0'),('10','2300662','0')
Duplicate entry '10-2300663' for key 'stats_table_id'

Why? In the stats.inc.php you declared two keys with the same integer "id"

=== Fatal error during creation of database ebd_quoridor_389 Not logged ===

Check that you didn't use $g_user or getCurrentPlayerId() in setupNewGame() function or in an 'args' function of your state.

As these functions are not consequences of a user action, there is no current player defined.

As a general rule, you should use getActivePlayerId() and not getCurrentPlayerId(). See the [http://www.slideshare.net/boardgamearena/bga-studio-focus-on-bga-game-state-machine presentation on the game state machine] for more information.

=== Warning: Invalid argument supplied for foreach() in table.game.php ===

Warning: Invalid argument supplied for foreach() in /var/tournoi/release/tournoi-151226-1240-gs/www/game/module/table/table.game.php on line 129
Fatal error: Cannot unset string offsets in /var/tournoi/release/tournoi-151226-1240-gs/www/game/module/table/table.game.php on line 143

That appears when your arg* function that suppose to return array of state arguments returns a scalar (a non-array) value

=== The server reported an error ===

During table creation: "The server reported an error" error shown and nothing else.

If you cannot even create a table - there is syntax error in gameinfos.php, check it, reload it from management panel.
If still no luck copy clean version from template https://github.com/elaskavaia/bga-sharedcode/blob/master/gameinfos.inc.php

== Predefined server errors ==

=== Unexpected error: Unexpected final game state (XX) ===

The action function does not transition to any state, i.e.
function selectField($field) {
self::checkAction ( 'selectField' );
if ($field!=0) $this->gamestate->nextState ( 'next' );
}
Here if $field is 0 there is no transition

=== This game action is impossible right now ===

Check the game log. Usually your state does not define the action you trying to perform in 'possibeactions' array.

=== Unexpected error: This transition (playerTurn) is impossible at this state (42) ===

This is pretty self explanatory. Function nextState() takes transition name not a state name, so you probably did not
define this transition that the given state

== Game interface hangs during reload or on start ==

Showing "Application Loading..."

=== Javascript error: During pageload undefined no_stack_avail Script: ===

This error usually has no useful data, but it means you called somes API that require a callback and did not define callback function, i.e
in dojo.connect, this.connectClass, dojo.subscribe, etc

this.connectClass('field', 'onclick', 'onField'); // <-- onField is not defined

=== Other errors with "Application loading..." ===

You probably have a syntax error in your Javascript code, and the interface refuses to load.

To find this error, check if there is an error message in the Javascript console (F12).

If there is really nothing on the log, it's probably that the system was unable to load your Javascript because of an syntax error that affect the structure of the Javascript file, typically a missing "}" or a missing "," after a method definition.

If you have "Uncaught ReferenceError: bgagame is not defined" you have major syntax error in your js file, you should see some other clues in the log where the errors is.

=== Unexpected Syntax Error: ===

No further details in the log. When log is filling with some social connect errors.

Possible Reason: Syntax error in of the php script which is loaded before the start, such as gameoptions.inc.php, gameinfos.inc.php and such.

=== Game interface spins in a loop throwing error ===

Errors is something like "Cannot read property 'is_ai' of undefined". Cannot restart the game because cannot access UI to stop.
Likely you get in actplayer state with player id == 0. The only way to fix it is to edit database, globals index == 2 set player id to one of your test dudes
(can copy from row 5 for example).

== Type conversion / juggling errors ==

=== On php side I get a number instead of string I expect ===

$num = 3;
$meeple = "meeple_" + $num; // <-- suppose to be "meeple_3"!

When you switch between JS and PHP it easy to type this and not notice the +. Plus sign (+) in php does not mean string concatenation (in javascript does!),
in php + means integer arithmetic. So change + to . (dot)

=== On php side my string comparison does not work ===

if ($color == '4baae2' || $color == '000000') {
}

Apparently you should not be using '==' in php to compare strings! You should use '==='. The (==) operator will typecast the strings
to numbers then do comparison!
Its not very apparent because usually you can get away with it, but not when strings resemble numbers like hex 'colors'.

=== Integer columns in the database are returned as strings ===

This is normal PHP behavior. All fields are returned as string type, regardless of their actual type in the database. This also applies to global variables accessed via getGameStateValue(), since they are stored in a database table.

You can use type-casting to convert them to the correct type after they come out of the database.

$myValueInt = (int)self::getGameStateValue(GLOBAL_ROUND_NUMBER);

or

$sql = "SELECT my_int_column FROM my_table WHERE my_condition";
$myResult = self::getUniqueValueFromDB($sql); <-- this is a string
$myResultAsInt = (int)$myResult;

https://stackoverflow.com/questions/5323146/mysql-integer-field-is-returned-as-string-in-php

== Zombie mode ==

=== Unexpected error: Propagating error from GS 1 (method: zombie): Not logged ===

You are probably calling getCurrentPlayerId() or getCurrentPlayerName() in your zombieTurn method or any of the methods it uses. Instead, use the $active_player_id provided as parameter to zombieTurn().

=== Unexpected error: Can't manage zombie player in this game state ===

Despite what the message suggests, this error has nothing to do with your state machine. It is caused by an exception in the zombie code. It could be an undefined value sent to a database query. Check the unexpected exceptions log. It could also be the same problem as above, so look for getCurrentPlayerId() or getCurrentPlayerName() in your zombieTurn method.

=== Unexpected error: Wrong formatted data from BGA gameserver 1 (method: zombie): ===

This is almost certainly an undefined value in PHP code. Look for a warning or error message in the game replay log on the right side of the table UI.

=== Unexpected error: BGA gameserver 1 do not respond (method: zombie) (timeout: cluster) ===

You are trying to end the game from a zombie method. This is not allowed. The zombie logic must continue the game as best it can. See [[Main_game_logic:_yourgamename.game.php#Zombie_mode|Zombie mode]] for more info.

== Other errors ==

=== When I do a move, I got "Move recorded, waiting for update ..." forever ===

"Move recorded" means that your ajaxcall request has been sent to the server and returned normally.

"Waiting for update" means that your client interface is waiting for some notifications from the server that correspond to the move we just did.

If this message stays forever, it is probably that your PHP code does not send any notification when the move happens, which is abnormal. To fix this: add a notifyAllPlayers or a notifyPlayer call in your PHP code.

=== When I do a move, I get "Sending move to server..." the nothing and game resets to state before the move ===

Its possible that server code get into infinite loops or thinks too much, in which case it will timeout and will be aborted without any extra logs (and any db transaction you saw in the log won't be committed). You will usually see "Unable to connect to server" message on console in this case. You have to put more logging into server
to trace where it hangs.

=== Some player action is triggered randomly when I click somewhere on the game area ===

You probably used "dojo.connect" on a null object. In this case, dojo.connect associate the event (ex: "onclick") to the whole game area.

Most of the time it happens in this situation, when my_object element does not exists:
<pre>
dojo.connect( $("my_object"), "onclick", this, function() {
...
}
</pre>

To determine if this is the case, place "alert( $("my_object") )" before the dojo.connect to check if the object exists or not.

=== Javascript does not know how to sum two numbers ===

Be careful when you manipulate integers returned by notifications: most of the time, Javascript considers they are Strings and not Integers.

As a result:
<pre>
var i=1;
i += notif.args.increment; // With notif.args.increment='1'
alert( i ); // i=11 instead of 2 !! Javascript concatenate 2 strings !
</pre>

To solve this, you should use the "toint" function:
<pre>
var i=1;
i += toint( notif.args.increment ); // With notif.args.increment='1'
alert( i ); // i=2 :)
</pre>

=== Javascript: do not use substr with negative numbers ===

To get the last characters of a string, use "slice" instead of "substr" which has a bug on IE:
<pre>
var three_last_characters = string.substr( -3 ); // Wrong
var three_last_characters = string.slice( -3 ); // Correct
</pre>

=== Game "spontaneously" transition to a new state without user input ===

Make sure on php side you have no code after $this->gamestate->nextState(...) code.
Because if you do accidentally have code that goes to another state it will cause another state transition without user interaction.

function selectField($field) {
self::checkAction ( 'selectField' );
if ($field!=0) $this->gamestate->nextState ( 'next' );
$this->gamestate->nextState ( 'last' ); // <-- here is missing else, so it will cause double state transition
}

Main game logic: Game.php

2020-07-04T09:12:38Z

Brainchild: Added a note about zombie mode in two-player games

{{Studio_Framework_Navigation}}

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

== File Structure ==

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

Here is the basic structure:

* EmptyGame (constructor): where you define global variables.
* setupNewGame: initial setup of the game.
* getAllDatas: where you retrieve all game data during a complete reload of the game.
* getGameProgression: where you compute the game progression indicator.
* Utility functions: your utility functions.
* Player actions: the entry points for players actions.
* Game state arguments: methods to return additional data on specific game states ([http://en.doc.boardgamearena.com/Your_game_state_machine:_states.inc.php#args more info here]).
* Game state actions: the logic to run when entering a new game state ([http://en.doc.boardgamearena.com/Your_game_state_machine:_states.inc.php#action more info here]).
* zombieTurn: what to do it's the turn of a zombie player.

== Accessing player information ==

'''Important''': In the following methods, be mindful of the difference between the "active" player and the "current" player. The '''active''' player is the player whose turn it is - not necessarily the player who sent a request! The '''current''' player is the player who sent the request and will see the results returned by your methods: not necessarily the player whose turn it is!

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

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

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

; loadPlayersBasicInfos()
: Get an associative array with generic data about players (ie: not game specific data).
: The key of the associative array is the player id. The returned table is cached, so ok to call multiple times without performance concerns.
: The content of each value is:
: * player_name - the name of the player
: * player_color (ex: ff0000) - the color code of the player
: * player_no - the position of the player at the start of the game in natural table order, i.e. 1,2,3

; getCurrentPlayerId()
: Get the "current_player". The current player is the one from which the action originated (the one who sent the request).
: '''Be careful''': This is not necessarily the active player!
: In general, you shouldn't use this method, unless you are in "multiplayer" state.
: '''Very important''': in your setupNewGame and zombieTurn function, you must never use getCurrentPlayerId() or getCurrentPlayerName(), otherwise it will fail with a "Not logged" error message (these actions are triggered from the main site and propagated to the gameserver from a server, not from a browser. As a consequence, there is no current player associated to these actions).

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

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

; isCurrentPlayerZombie()
: Check the "current_player" zombie status. If true, player is zombie, i.e. left or was kicked out of the game.

== Accessing the database ==

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

'''IMPORTANT'''

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

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

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

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

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

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

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

</pre>

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

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

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

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

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

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

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

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

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

</pre>

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

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

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

; escapeStringForDB( $string )
: You must use this function on every string type data in your database that contains unsafe data.
: (unsafe = can be modified by a player).
: This method makes sure that no SQL injection will be done through the string used.
: Note: if you using standard types in ajax actions, like AT_alphanum it is sanitized before arrival,
: this is only needed if you manage to get unchecked string, like in the games where user has to enter text as a response.

<pre>

</pre>

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

== Use globals ==

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

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

'''initGameStateLabels'''

This method should be located at the beginning of ''yourgamename.php.'' This is where you define the globals used in your game logic, by assigning them IDs.

You can define up to 79 globals, with IDs from 10 to 89 (inclusive). You must '''not''' use globals outside this range, as those values are used by other components of the framework.

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

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

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

'''getGameStateValue( $value_label )'''

Retrieve the current value of a global.

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

Set the current value of a global.

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

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

Return the final value of the global.

== Game states and active players ==

=== Activate player handling ===

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

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

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

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

=== Multiactivate player handling ===

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

; $this->gamestate->setAllPlayersNonMultiactive( $next_state )
: All playing players are made inactive. Transition to next state

; $this->gamestate->setPlayersMultiactive( $players, $next_state, $bExclusive = false )
: Make a specific list of players active during a multiactive gamestate. Update notification is sent to all players who's state changed.
: "players" is the array of player id that should be made active.
: If "exclusive" parameter is not set or false it doesn't deactivate other previously active players. If its set to true, the players who will be multiactive at the end are only these in "$players" array

: In case "players" is empty, the method trigger the "next_state" transition to go to the next game state.
: returns true if state transition happened, false otherwise

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

; $this->gamestate->updateMultiactiveOrNextState( $next_state_if_none )
: Sends update notification about multiplayer changes. All multiactive set* functions above do that, however if you want to change state manually using db queries for complex calculations, you have to call this yourself after. Do not call this if you calling one of the other setters above.
Example: you have player teams and you want to activate all players in one team
<pre>
$sql = "UPDATE player SET player_is_multiactive='0'";
self::DbQuery( $sql );
$sql = "UPDATE player SET player_is_multiactive='1' WHERE player_id='$player_id' AND player_team='$team_no'";
self::DbQuery( $sql );

$this->gamestate->updateMultiactiveOrNextState( 'error' );
</pre>

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

=== States functions ===
; $this->gamestate->nextState( $transition )
: Change current state to a new state. Important: the $transition parameter is the name of the transition, and NOT the name of the target game state, see [[Your game state machine: states.inc.php]] for more information about states.

; $this->checkAction( $actionName, $bThrowException=true )
: Check if an action is valid for the current game state, and optionally, throw an exception if it isn't.
: The action is valid if it is listed in the "possibleactions" array for the current game state (see game state description).
: This method MUST be the first one called in ALL your PHP methods that handle player actions, in order to make sure a player doesn't perform an action not allowed by the rules at the point in the game.
: If "bThrowException" is set to "false", the function returns '''false''' in case of failure instead of throwing an exception. This is useful when several actions are possible, in order to test each of them without throwing exceptions.

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

; $this->gamestate->state()
: Get an associative array of current game state attributes, see [[Your game state machine: states.inc.php]] for state attributes.
$state=$this->gamestate->state(); if( $state['name'] == 'myGameState' ) {...}

== Players turn order ==

'''getNextPlayerTable()'''

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

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

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

'''getPrevPlayerTable()'''

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

'''getPlayerAfter( $player_id )'''

Get player playing after given player in natural playing order.

'''getPlayerBefore( $player_id )'''

Get player playing before given player in natural playing order.

Note: There is no API to modify this order, if you have custom player order you have to maintain it in your database
and have custom function to access it.

== Notify players ==

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

'''IMPORTANT'''

Notifications are sent at the very end of the request, when it ends normally. It means that if you throw an exception for any reason (ex: move not allowed), no notifications will be sent to players.
Notifications sent between the game start (setupNewGame) and the end of the "action" method of the first active state will never reach their destination.

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

Send a notification to all players of the game.

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

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

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

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

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

You can use arguments in your notification_log strings, that refers to values defines in the "notification_args" argument (see below).
Note: Make sure you only use single quotes ('), otherwise PHP will try to interpolate the variable and will ignore the values in the args array.

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

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

Complete notifyAllPlayers example (from "Reversi"):

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

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

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

'''Important''': this array is serialized to be sent to the browsers, and will be saved with the notification to be able to replay the game later. If it is too big, it can make notifications slower / less reliable, and replay archives very big (to the point of failing). So as a general rule, you should send only the minimum of information necessary to update the client interface with no overhead in order to keep the notifications as light as possible.

Note: you CAN use some HTML inside your notification log, however it not recommended for many reasons:
* Its bad architecture, ui elements leak into server now you have to manage ui in many places
* If you decided to change something in ui in future version, old games reply and tutorials may not work, since they use stored notifications
* When you read log preview for old games its unreadable (this is log before you enter the game reply, useful for troubleshooting or game analysis)
* Its more data to transfer and store in db
* Its nightmare for translators, at least don't put HTML tags inside the "clienttranslate" method. You can use a notification argument instead, and provide your HTML through this argument.

If you still want to have pretty pictures in the log check this [[BGA_Studio_Cookbook#Inject_images_and_styled_html_in_the_log]].

If your notification contains some phrases that build programmatically you may need to use recursive notifications. In this case the argument can be not only the string but
an array itself, which contains 'log' and 'args', i.e.

$this->notifyAllPlayers('playerLog',clienttranslate('Game moves ${token_name_rec}'),
['token_name_rec'=>['log'=>'${token_name} #${token_number}',
'args'=> ['token_name'=>clienttranslate('Boo'), 'token_number'=>$number, 'i18n'=>['token_name'] ]
]
]);

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

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

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

Important: the variable for player name must be ${player_name} in order to be highlighted with the player color in the game log

== About random and randomness ==

A large number of board games rely on random, most often based on dice, cards shuffling, picking some item in a bag, and so on. This is very important to ensure a high level of randomness for each of these situations.

Here's are a list of techniques you should use in these situations, from the best to the worst.

=== Dices and bga_rand ===

'''bga_rand( min, max )'''
This is a BGA framework function that provides you a random number between "min" and "max" (included), using the best available random method available on the system.

This is the preferred function you should use, because we are updating it when a better method is introduced.

At now, bga_rand is based on the PHP function "random_int", which ensure a cryptographic level of randomness.

In particular, it is '''mandatory''' to use it for all '''dice throw''' (ie: games using other methods for dice throwing will be rejected by BGA during review).

Note: rand() and mt_rand() are deprecated on BGA and should not be used anymore, as their randomness is not as good as "bga_rand".

=== shuffle and cards shuffling ===

To shuffle items, like a pile of cards, the best way is to use the BGA PHP [[Deck]] component and to use "shuffle" method. This ensure you that the best available shuffling method is used, and that if in the future we improve it your game will be up to date.

At now, the Deck component shuffle method is based on PHP "shuffle" method, which has a quite good randomness (even it is not as good as bga_rand). In consequence, we accept other shuffling methods during reviews, as long as their are based on PHP "shuffle" function (or similar, like "array_rand").

=== Other methods ===

Mysql "RAND()" function has not enough randomness to be a valid method to get a random element on BGA. This function has been used in some existing games and has given acceptable results, but now it should be avoided and you should use other methods instead.

== Game statistics ==

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

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

'''initStat( $table_or_player, $name, $value, $player_id = null )'''

Create a statistic entry with a default value.
This method must be called for each statistics of your game, in your setupNewGame method.

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

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

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

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

Set a statistic $name to $value.

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

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

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

Increment (or decrement) specified statistic value by $delta value. Same behavior as setStat function.

'''getStat( $name, $player_id = null )'''

Return the value of statistic specified by $name. Useful when creating derivative statistics such as average.

== Translations ==

See [[Translations]]

== Manage player scores and Tie breaker ==

=== Normal scoring ===

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

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

Examples:
<pre>

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

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

</pre>

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

=== Tie breaker ===

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

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

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

When you are using "player_score_aux" functionality, you must describe the formula to use in your gameinfos.inc.php file like this:

<pre>
'tie_breaker_description' => totranslate("Describe here your tie breaker formula"),
</pre>

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

=== Co-operative game ===

To make everyone lose in full-coop game:

Add the following in gameinfos.inc.php :
'is_coop' => 1, // full cooperative

And score zero to everyone.

=== Semi-coop ===

If the game is not full-coop, then everyone lose = everyone is tie. I.e. set score to 0 to everybody.

=== Only "winners" and "losers" ===

For some games, there is only a group (or a single) "winner", and everyone else is a "loser", with no "end of game rank" (1st, 2nd, 3rd...).

Examples:
* Coup
* Not Alone
* Werewolves
* Quantum

In this case:
* Set the scores so that the winner has the best score, and the other players have the same (lower) score.
* Add the following lines to gameinfos.php:

<pre>
// If in the game, all losers are equal (no score to rank them or explicit in the rules that losers are not ranked between them), set this to true
// The game end result will display "Winner" for the 1st player and "Loser" for all other players
'losers_not_ranked' => true,
</pre>

Werewolves and Coup are implemented like this, as you can see here:
* https://boardgamearena.com/#!gamepanel?game=werewolves&section=lastresults
* https://boardgamearena.com/#!gamepanel?game=coupcitystate&section=lastresults

Adding this has the following effects:
* On game results for this game, "Winner" or "Loser" is going to appear instead of the usual "1st, 2nd, 3rd, ...".
* When a game is over, the result of the game will be "End of game: Victory" or "End of game: Defeat" depending on the result of the CURRENT player (instead of the usual "Victory of XXX").
* When calculating ELO points, if there is at least one "Loser", no "victorious" player can lose ELO points, and no "losing" player can win ELO point. Usually it may happened because being tie with many players with a low rank is considered as a tie and may cost you points. If losers_not_ranked is set, we prevent this behavior and make sure you only gain/loss ELO when you get the corresponding results.

Important: this SHOULD NOT be used for cooperative games (see is_coop parameter), or for 2 players games (it makes no sense in this case).

=== Solo ===

If game supports solo variant, a negative score means defeat, a positive score means victory.

=== Player elimination ===

In some games, this is useful to eliminate a player from the game in order he/she can start another game without waiting for the current game end.

This case should be rare. Please don't use player elimination feature if some player just has to wait the last 10% of the game for game end. This feature should be used only in games where players are eliminated all along the game (typical examples: "Perudo" or "The Werewolves of Miller's Hollow").

Usage:

* Player to eliminate should NOT be active anymore (preferably use the feature in a "game" type game state).
* In your PHP code:
self::eliminatePlayer( <player_to_eliminate_id> );
* the player is informed in a dialog box that he no longer have to played and can start another game if he/she wants too (whith buttons "stay at this table" "quit table and back to main site"). In any case, the player is free to start & join another table from now.
* When your game is over, all players who have been eliminated before receive a "notification" (the small "!" icon on the top right of the BGA interface) that indicate them that "the game has ended" and invite them to review the game results.

=== Scoring Helper functions ===

// get score
function dbGetScore($player_id) {
return $this->getUniqueValueFromDB("SELECT player_score FROM player WHERE player_id='$player_id'");
}

// set score
function dbSetScore($player_id, $count) {
$this->DbQuery("UPDATE player SET player_score='$count' WHERE player_id='$player_id'");
}

// set aux score (tie breaker)
function dbSetAuxScore($player_id, $score) {
$this->DbQuery("UPDATE player SET player_score_aux=$score WHERE player_id='$player_id'");
}

// increment score (can be negative too)
function dbIncScore($player_id, $inc) {
$count = $this->dbGetScore($player_id);
if ($inc != 0) {
$count += $inc;
$this->dbSetScore($player_id, $count);
}
return $count;
}

== Reflexion time ==

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

== Undo moves ==

Please read our [[BGA Undo policy]] before.

'''Important''': Before using these methods, you must also add the following to your "gameinfos.inc.php" file, otherwise these methods are ineffective:
'db_undo_support' => true

; function undoSavepoint( )
: Save the whole game situation inside an "Undo save point".
: There is only ONE undo save point available (see BGA Undo policy).

; function undoRestorePoint()
: Restore the situation previously saved as an "Undo save point".
: You must make sure that the active player is the same after and before the undoRestorePoint (ie: this is your responsibility to ensure that the player that is active when this method is called is exactly the same than the player that was active when the undoSavePoint method has been called).

== Managing errors and exceptions ==

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

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

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

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

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

== Zombie mode ==

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

While developing your zombie mode, keep in mind that:
* Do not refer to the rules, because this situation is not planned by the rules.
* Try to figure that you are playing with your friends and one of them has to leave: how can we finish the game without killing the spirit of the game?
* The idea is NOT to develop an artificial intelligence for the game.
* Do not try to end the game early, even in a two-player game. The zombie is there to allow the game to continue, not to end it. Trying to end the game is not supported by the framework and will likely cause unexpected errors.

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

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

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

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

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

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

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

'''Very important''': your zombie code will be called when the player leaves the game. This action is triggered from the main site and propagated to the gameserver from a server, not from a browser. As a consequence, there is no current player associated to this action. In your zombieTurn function, you must '''never''' use getCurrentPlayerId() or getCurrentPlayerName(), otherwise it will fail with a "Not logged" error message.

== Player color preferences ==

BGA players (Club members) may now choose their preferred color for playing. For example, if they are used to play green for every board game, they can select "green" in their BGA preferences page.

Making your game compatible with colors preferences is very easy and requires only 1 line of PHP and 1 configuration change :

On your gameinfos.inc.php file, add the following lines :

// Favorite colors support : if set to "true", support attribution of favorite colors based on player's preferences (see reattributeColorsBasedOnPreferences PHP method)
'favorite_colors_support' => true,

Then, on your main <your_game>.game.php file, find the "reloadPlayersBasicInfos" call in your "setupNewGame" method and replace :

$sql .= implode( $values, ',' );
self::DbQuery( $sql );
self::reloadPlayersBasicInfos();

By :

$sql .= implode( $values, ',' );
self::DbQuery( $sql );
self::reattributeColorsBasedOnPreferences( $players, array( /* LIST HERE THE AVAILABLE COLORS OF YOUR GAME INSTEAD OF THESE ONES */"ff0000", "008000", "0000ff", "ffa500", "773300" ) );
self::reloadPlayersBasicInfos();

The "reattributeColorsBasedOnPreferences" method reattributes all colors, taking into account players color preferences and available colors.

Note that you must update the colors to indicate the colors available for your game.

2 important remarks :
* for some games (ex : Chess), the color has an influence on a mechanism of the game, most of the time by giving a special advantage to a player (ex : Starting the game). Color preference mechanism must NOT be used in such a case.
* your logic should NEVER consider that the first player has the color X, that the second player has the color Y, and so on. If this is the case, your game will NOT be compatible with reattributeColorsBasedOnPreferences as this method attribute colors to players based on their preferences and not based as their order at the table.

Colours currently listed as a choice in preferences:

* #ff0000 Red
* #008000 Green
* #0000ff Blue
* #ffa500 Yellow
* #000000 Black
* #ffffff White
* #e94190 Pink
* #982fff Purple
* #72c3b1 Cyan
* #f07f16 Orange
* #bdd002 Khaki green
* #7b7b7b Gray

== Debugging and Tracing ==

To debug php code you can use some tracing functions available from the parent class such as debug, trace, error, warn, dump.

self::debug("Ahh!");
self::dump('my_var',$my_var);

See [[Practical_debugging]] section for complete information about debugging interfaces and where to find logs.

Troubleshooting

2020-07-04T09:03:23Z

Brainchild:

{{Studio_Framework_Navigation}}

Describing common errors which is hard to understand and debug

== Game does not start at all ==

=== Undefined offset: 0 in table/table.game.php on line 830 ===

You are likely calling self::getActivePlayerName () during setupNewGame()

=== Unexpected error: Wrong formatted data from BGA gameserver 1 (method: createGame): ... ===

This is generic message usually followed by exact position in your source code, and usually its syntax error in one of yours php script

=== Unexpected error: Propagating error from GS 1 (method: createGame): Fatal error during yourgame setup: Not logged ===

Calling self::getCurrentPlayerId () or using $g_user from 'args' state function, see also below

=== Unexpected error: Propagating error from GS 1 (method: createGame): Fatal error during yourgame setup: Unknow player statistic: ===

Calling self::incStat() with second parameter which is an empty string

=== Unexpected error: Propagating error from GS 1 (method: createGame): Fatal error during yourgame setup: Error while processing SQL request: INSERT INTO stats ... ===

Fatal error during yourgame setup: Error while processing SQL request: INSERT INTO stats (stats_type, stats_player_id, stats_value) VALUES ('10','2300663','0'),('10','2300662','0')
Duplicate entry '10-2300663' for key 'stats_table_id'

Why? In the stats.inc.php you declared two keys with the same integer "id"

=== Fatal error during creation of database ebd_quoridor_389 Not logged ===

Check that you didn't use $g_user or getCurrentPlayerId() in setupNewGame() function or in an 'args' function of your state.

As these functions are not consequences of a user action, there is no current player defined.

As a general rule, you should use getActivePlayerId() and not getCurrentPlayerId(). See the [http://www.slideshare.net/boardgamearena/bga-studio-focus-on-bga-game-state-machine presentation on the game state machine] for more information.

=== Warning: Invalid argument supplied for foreach() in table.game.php ===

Warning: Invalid argument supplied for foreach() in /var/tournoi/release/tournoi-151226-1240-gs/www/game/module/table/table.game.php on line 129
Fatal error: Cannot unset string offsets in /var/tournoi/release/tournoi-151226-1240-gs/www/game/module/table/table.game.php on line 143

That appears when your arg* function that suppose to return array of state arguments returns a scalar (a non-array) value

=== The server reported an error ===

During table creation: "The server reported an error" error shown and nothing else.

If you cannot even create a table - there is syntax error in gameinfos.php, check it, reload it from management panel.
If still no luck copy clean version from template https://github.com/elaskavaia/bga-sharedcode/blob/master/gameinfos.inc.php

== Predefined server errors ==

=== Unexpected error: Unexpected final game state (XX) ===

The action function does not transition to any state, i.e.
function selectField($field) {
self::checkAction ( 'selectField' );
if ($field!=0) $this->gamestate->nextState ( 'next' );
}
Here if $field is 0 there is no transition

=== This game action is impossible right now ===

Check the game log. Usually your state does not define the action you trying to perform in 'possibeactions' array.

=== Unexpected error: This transition (playerTurn) is impossible at this state (42) ===

This is pretty self explanatory. Function nextState() takes transition name not a state name, so you probably did not
define this transition that the given state

== Game interface hangs during reload or on start ==

Showing "Application Loading..."

=== Javascript error: During pageload undefined no_stack_avail Script: ===

This error usually has no useful data, but it means you called somes API that require a callback and did not define callback function, i.e
in dojo.connect, this.connectClass, dojo.subscribe, etc

this.connectClass('field', 'onclick', 'onField'); // <-- onField is not defined

=== Other errors with "Application loading..." ===

You probably have a syntax error in your Javascript code, and the interface refuses to load.

To find this error, check if there is an error message in the Javascript console (F12).

If there is really nothing on the log, it's probably that the system was unable to load your Javascript because of an syntax error that affect the structure of the Javascript file, typically a missing "}" or a missing "," after a method definition.

If you have "Uncaught ReferenceError: bgagame is not defined" you have major syntax error in your js file, you should see some other clues in the log where the errors is.

=== Unexpected Syntax Error: ===

No further details in the log. When log is filling with some social connect errors.

Possible Reason: Syntax error in of the php script which is loaded before the start, such as gameoptions.inc.php, gameinfos.inc.php and such.

=== Game interface spins in a loop throwing error ===

Errors is something like "Cannot read property 'is_ai' of undefined". Cannot restart the game because cannot access UI to stop.
Likely you get in actplayer state with player id == 0. The only way to fix it is to edit database, globals index == 2 set player id to one of your test dudes
(can copy from row 5 for example).

== Type conversion / juggling errors ==

=== On php side I get a number instead of string I expect ===

$num = 3;
$meeple = "meeple_" + $num; // <-- suppose to be "meeple_3"!

When you switch between JS and PHP it easy to type this and not notice the +. Plus sign (+) in php does not mean string concatenation (in javascript does!),
in php + means integer arithmetic. So change + to . (dot)

=== On php side my string comparison does not work ===

if ($color == '4baae2' || $color == '000000') {
}

Apparently you should not be using '==' in php to compare strings! You should use '==='. The (==) operator will typecast the strings
to numbers then do comparison!
Its not very apparent because usually you can get away with it, but not when strings resemble numbers like hex 'colors'.

=== Integer columns in the database are returned as strings ===

This is normal PHP behavior. All fields are returned as string type, regardless of their actual type in the database. This also applies to global variables accessed via getGameStateValue(), since they are stored in a database table.

You can use type-casting to convert them to the correct type after they come out of the database.

$myValueInt = (int)self::getGameStateValue(GLOBAL_ROUND_NUMBER);

or

$sql = "SELECT my_int_column FROM my_table WHERE my_condition";
$myResult = self::getUniqueValueFromDB($sql); <-- this is a string
$myResultAsInt = (int)$myResult;

https://stackoverflow.com/questions/5323146/mysql-integer-field-is-returned-as-string-in-php

== Zombie mode ==

=== Unexpected error: Propagating error from GS 1 (method: zombie): Not logged ===

You are probably calling getCurrentPlayerId() or getCurrentPlayerName() in your zombieTurn method or any of the methods it uses. Instead, use the $active_player_id provided as parameter to zombieTurn().

=== Unexpected error: Can't manage zombie player in this game state ===

Same as above. Check if you are calling getCurrentPlayerId() or getCurrentPlayerName() in your zombieTurn method and replace it with active_player_id for the zombie.

=== Unexpected error: BGA gameserver 1 do not respond (method: zombie) (timeout: cluster) ===

You are trying to end the game from a zombie method. This is not allowed. The zombie logic must continue the game as best it can. See [[Main_game_logic:_yourgamename.game.php#Zombie_mode|Zombie mode]] for more info.

== Other errors ==

=== When I do a move, I got "Move recorded, waiting for update ..." forever ===

"Move recorded" means that your ajaxcall request has been sent to the server and returned normally.

"Waiting for update" means that your client interface is waiting for some notifications from the server that correspond to the move we just did.

If this message stays forever, it is probably that your PHP code does not send any notification when the move happens, which is abnormal. To fix this: add a notifyAllPlayers or a notifyPlayer call in your PHP code.

=== When I do a move, I get "Sending move to server..." the nothing and game resets to state before the move ===

Its possible that server code get into infinite loops or thinks too much, in which case it will timeout and will be aborted without any extra logs (and any db transaction you saw in the log won't be committed). You will usually see "Unable to connect to server" message on console in this case. You have to put more logging into server
to trace where it hangs.

=== Some player action is triggered randomly when I click somewhere on the game area ===

You probably used "dojo.connect" on a null object. In this case, dojo.connect associate the event (ex: "onclick") to the whole game area.

Most of the time it happens in this situation, when my_object element does not exists:
<pre>
dojo.connect( $("my_object"), "onclick", this, function() {
...
}
</pre>

To determine if this is the case, place "alert( $("my_object") )" before the dojo.connect to check if the object exists or not.

=== Javascript does not know how to sum two numbers ===

Be careful when you manipulate integers returned by notifications: most of the time, Javascript considers they are Strings and not Integers.

As a result:
<pre>
var i=1;
i += notif.args.increment; // With notif.args.increment='1'
alert( i ); // i=11 instead of 2 !! Javascript concatenate 2 strings !
</pre>

To solve this, you should use the "toint" function:
<pre>
var i=1;
i += toint( notif.args.increment ); // With notif.args.increment='1'
alert( i ); // i=2 :)
</pre>

=== Javascript: do not use substr with negative numbers ===

To get the last characters of a string, use "slice" instead of "substr" which has a bug on IE:
<pre>
var three_last_characters = string.substr( -3 ); // Wrong
var three_last_characters = string.slice( -3 ); // Correct
</pre>

=== Game "spontaneously" transition to a new state without user input ===

Make sure on php side you have no code after $this->gamestate->nextState(...) code.
Because if you do accidentally have code that goes to another state it will cause another state transition without user interaction.

function selectField($field) {
self::checkAction ( 'selectField' );
if ($field!=0) $this->gamestate->nextState ( 'next' );
$this->gamestate->nextState ( 'last' ); // <-- here is missing else, so it will cause double state transition
}

Stock

2020-07-01T20:53:11Z

Brainchild: Added noupdate param to removeFromStock

{{Studio_Framework_Navigation}}

'''Stock''' is a javascript component that you can use in your game interface to display a set of elements of the same size that need to be arranged in single or multiple lines.

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

Examples of stock use cases:

* Display a set of cards, typically hands (examples: ''Hearts'', ''Seasons'', ''The Boss'', ''Race for the Galaxy'').
* Display items in player panels (examples: ''Takenoko'', ''Amyitis'', ...)
* ... Many other situations. For example, black dice and cubes on cards in ''Troyes'' are displayed with stock components.

Using stock:

* Your items are arranged nicely and sorted by type.
* When adding or removing items to a set, all items slide smoothly to their new position in the set.
* Selecting and unselecting items are built-in functions.
* You don't have to worry about inserting/removing HTML code; the entire life cycle of the stock is managed by the component.

== Using stock: a simple example ==

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

First, don't forget to add "ebg/stock" as a dependency in your js file:

<pre>
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/stock" /// <==== HERE
],
</pre>

The stock is initialized in the Javascript "setup" method like this:

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

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

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

Here's how we tell stock what items to display:

<pre>
// Specify that there are 13 images per row in the CSS sprite image
this.playerHand.image_items_per_row = 13;

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

Explanation:

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

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

From now on, if we need to add a card - for example, the 5 of Hearts - to a player's hand, we can do this:

<pre>
this.playerHand.addToStock( this.getCardUniqueId( 2 /* 2=hearts */, 5 ) );
</pre>

In reality, cards have some IDs, which are useful to manipulate them. This is the reason we are using "addToStockWithId" instead:

<pre>
this.playerHand.addToStockWithId( this.getCardUniqueId( 2 /* 2=hearts */, 5 ), my_card_id );
</pre>

If afterwards we want to remove this card from the stock:

<pre>
this.playerHand.removeFromStockById( my_card_id );
</pre>

== Complete stock component reference ==

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

With create, you create a new stock component.

Parameters:
* page: the container page. Usually: "this".
* container_div: the container "div" element (a void div element in your template, with an id).
* width and height (in pixels) for the stock component.

(See ''Hearts'' example above).

'''count():'''

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

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

Define a new type of item and add it to the stock.

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

Parameters:
* type: ID of the type to add. You can choose any positive integer. All item types must have distinct IDs.
* weight: weight of items of this type. Weight value is used to sort items of the stock during the display. Note that you can specify the same weight for all items; in this case, they are not sorted and their order might change randomly at any time.
* image: URL of item image. Most of the time, you will use a CSS sprite for stock items, so you have to specify CSS sprite image here.

Be careful: you must specify the image url as this:

<pre>
g_gamethemeurl+'img/yourimage.png'
</pre>

* image_position: if "image" specify the URL of a CSS sprite, you must specify the position of the item image in this CSS sprite. For example, if you have a CSS sprite with 3 cubes with a size of 20x20 pixels each (so your CSS image has for example a size of 20x60 or 60x20), you specify "0" for the first cube image, 1 for the second, 2 for the third.

''Important'': if there is more than one line of items in your CSS sprite, you must specify how many items per line you have in your CSS sprite like this:

<pre>
// Specify that there are 10 image items per row in images used in "myStockObject" control.
this.myStockObject.image_items_per_row = 10;
</pre>

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

Add an item to the stock, with the specified type, but without a unique ID.

To make your life easier, in most cases we suggest you use '''addToStockWithId''' in order to give an ID to the item added. '''addToStock''' is suitable when you are using a stock to control items that are generic game materials that don't need to be addressed individually (example: a bunch of money tokens).

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

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

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

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

This is the same method as '''addToStock''', except that it also associates an ID with the newly created item.

This is especially useful:

* When you need to know which item(s) have been selected by the user (see '''getSelectedItems''').
* When you need to remove a specific item from the stock with '''removeFromStockById'''.

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

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

Remove an item of the specific type from the stock.

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

"noupdate" is an optional parameter. If set to "true" it will prevent the stock display from changing. This is useful when multiple (but not all) items are removed at the same time, to avoid ghost items appearing briefly. Be sure to call '''updateDisplay''' after all items are removed.

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

Remove an item with a specific ID from the stock.

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

"noupdate" is an optional parameter. If set to "true" it will prevent the stock display from changing. This is useful when multiple (but not all) items are removed at the same time, to avoid ghost items appearing briefly. Be sure to call '''updateDisplay''' after all items are removed.

'''removeAll()'''

Remove all items from the stock.

'''removeAllTo( to )'''

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

'''getPresentTypeList()'''

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

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

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

'''resetItemsPosition()'''

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

'''item_margin'''

By default, there is a margin of 5px between the items of a stock. You can change the member variable "item_margin" to change this.

Example:
<pre>
this.myStockControl.item_margin=5;
</pre>

'''changeItemsWeight( newWeights )'''

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

Items are immediately re-sorted with the new weight.

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

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

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

'''centerItems'''

Center the stock items in the middle of the stock container.
e.g. this.myStock.centerItems = true;

'''setSelectionMode( mode )'''

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

'''setSelectionAppearance( type )'''

For each stock control, you can specify a selection highlighting type:
* 'border': there will be a red border around selected items (this is the default). The attribute 'apparenceBorderWidth' can be used to manage the width of the border (in pixels).
* 'disappear': the selected item will fade out and disappear. This is useful when the selection has the effect of destroying the item.
* 'class': there will be an extra '''stockitem_selected''' css class added to the element when it is selected (and removed when unselected). You can override this class in the css file for your game.

By default this class definition is:
<pre>
.stockitem_selected {
border: 2px solid red ! important;
}
</pre>

If you want to override it (for example, to change the border color) add this in your <game>.css file:
<pre>
.stockitem_selected {
border: 2px solid orange ! important;
}
</pre>

'''isSelected( id )'''

Return a boolean indicating whether the specified item id has been selected.

'''selectItem( id )'''

Select the specified item.

'''unselectItem( id )'''

Unselect the specified item.

'''unselectAll()'''

Unselect all items of the stock.

'''onChangeSelection'''

This callback method is called when the player selects/unselects an item of the stock.

You can connect this to one of your methods like this:

<pre>
dojo.connect( this.myStockControl, 'onChangeSelection', this, 'onMyMethodToCall' );

(...)

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

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

Nota bene:
- The "control_name" argument is the ID (the "DOM" id) of the "div" container of your stock control. Using "control_name", you can use the same callback method for different Stock control and see which one trigger the method.
- The "item_id" argument is the stock ID (index) of the stock item that has just been selected/unselected.

'''getSelectedItems()'''

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

'''getUnselectedItems()'''

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

'''getAllItems()'''

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

'''getItemDivId(id)'''

Get the div id using the stock item id (to manipulate element properties directly).

'''getItemById(id)'''

Get the Stock item with the id in parameter
ex : return the object { type:1, id: 1001 }

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

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

By default, horizontal_overlap and vertical_overlap are 0.

When horizontal_overlap=20, it means that a stock item will overlap to only show 20% of the width of all the previous items. horizontal_overlap can't be greater than 100.

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

See the games "Jaipur" or "Koryŏ" to see examples of use of this function.

'''onItemCreate'''

Using onItemCreate, you can trigger a method each time a new item is added to the Stock, in order to customize it.

Complete example:
<pre>
// During "setup" phase, we associate our method "setupNewCard" with the creation of a new stock item:
this.myStockItem.onItemCreate = dojo.hitch( this, 'setupNewCard' );

(...)

// And here is our "setupNewCard":
setupNewCard: function( card_div, card_type_id, card_id )
{
// Add a special tooltip on the card:
this.addTooltip( card_div.id, _("Some nice tooltip for this item"), '' );

// Note that "card_type_id" contains the type of the item, so you can do special actions depending on the item type

// Add some custom HTML content INSIDE the Stock item:
dojo.place( this.format_block( 'jstpl_my_card_content', {
....
} ), card_div.id );
}

</pre>

== Tips when adding/removing items to/from Stock components ==

Most cases will be one of the following situations:

'''Situation A''':

When you add a card to a stock item, and this card is '''not''' coming from another stock:

* Use '''addToStockWithId''' with a "from" argument set to the element of your interface where the card should come from.

'''Situation B''':

When you add a card to a stock item, and this card is coming from another stock:

* On the destination Stock, use '''addToStockWithId''' with a "from" argument which is the HTML id of the corresponding item in the source Stock. For example, if the source stock id is "myHand", then the HTML id of card 48 is "myHand_item_48".
* Then, remove the source item with '''removeFromStockById'''.

(Note that it's important to do things in this order, because the source item must still exist when you use it as the origin of the slide.)

'''Situation C''':

When you move a card from a stock item to something that is not a stock item:

* Insert the card as a classic HTML template (dojo.place / this.format_block).
* Place it on the Stock item with '''this.placeOnObject''', using the Stock item HTML id (see above).
* Slide it to its new position with '''this.slideToObject'''.
* Remove the card from the Stock item with '''removeFromStockById'''.

Using the methods above, your cards should slide to, from, and between your Stock controls smoothly.

You can customize this (showing the default value):
<pre>

this.mystock.jstpl_stock_item= "<div id=\"${id}\" class=\"stockitem\" style=\"top:${top}px;left:${left}px;width:${width}px;height:${height}px;z-index:${position};background-image:url('${image}');\"></div>";
</pre>
To produce a different type of stock item

Troubleshooting

2020-06-06T10:40:26Z

Brainchild:

{{Studio_Framework_Navigation}}

Describing common errors which is hard to understand and debug

== Game does not start at all ==

=== Undefined offset: 0 in table/table.game.php on line 830 ===

You are likely calling self::getActivePlayerName () during setupNewGame()

=== Unexpected error: Wrong formatted data from BGA gameserver 1 (method: createGame): ... ===

This is generic message usually followed by exact position in your source code, and usually its syntax error in one of yours php script

=== Unexpected error: Propagating error from GS 1 (method: createGame): Fatal error during yourgame setup: Not logged ===

Calling self::getCurrentPlayerId () or using $g_user from 'args' state function, see also below

=== Unexpected error: Propagating error from GS 1 (method: createGame): Fatal error during yourgame setup: Unknow player statistic: ===

Calling self::incStat() with second parameter which is an empty string

=== Unexpected error: Propagating error from GS 1 (method: createGame): Fatal error during yourgame setup: Error while processing SQL request: INSERT INTO stats ... ===

Fatal error during yourgame setup: Error while processing SQL request: INSERT INTO stats (stats_type, stats_player_id, stats_value) VALUES ('10','2300663','0'),('10','2300662','0')
Duplicate entry '10-2300663' for key 'stats_table_id'

Why? In the stats.inc.php you declared two keys with the same integer "id"

=== Fatal error during creation of database ebd_quoridor_389 Not logged ===

Check that you didn't use $g_user or getCurrentPlayerId() in setupNewGame() function or in an 'args' function of your state.

As these functions are not consequences of a user action, there is no current player defined.

As a general rule, you should use getActivePlayerId() and not getCurrentPlayerId(). See the [http://www.slideshare.net/boardgamearena/bga-studio-focus-on-bga-game-state-machine presentation on the game state machine] for more information.

=== Warning: Invalid argument supplied for foreach() in table.game.php ===

Warning: Invalid argument supplied for foreach() in /var/tournoi/release/tournoi-151226-1240-gs/www/game/module/table/table.game.php on line 129
Fatal error: Cannot unset string offsets in /var/tournoi/release/tournoi-151226-1240-gs/www/game/module/table/table.game.php on line 143

That appears when your arg* function that suppose to return array of state arguments returns a scalar (a non-array) value

=== The server reported an error ===

During table creation: "The server reported an error" error shown and nothing else.

If you cannot even create a table - there is syntax error in gameinfos.php, check it, reload it from management panel.
If still no luck copy clean version from template https://github.com/elaskavaia/bga-sharedcode/blob/master/gameinfos.inc.php

== Predefined server errors ==

=== Unexpected error: Unexpected final game state (XX) ===

The action function does not transition to any state, i.e.
function selectField($field) {
self::checkAction ( 'selectField' );
if ($field!=0) $this->gamestate->nextState ( 'next' );
}
Here if $field is 0 there is no transition

=== This game action is impossible right now ===

Check the game log. Usually your state does not define the action you trying to perform in 'possibeactions' array.

=== Unexpected error: This transition (playerTurn) is impossible at this state (42) ===

This is pretty self explanatory. Function nextState() takes transition name not a state name, so you probably did not
define this transition that the given state

== Game interface hangs during reload or on start ==

Showing "Application Loading..."

=== Javascript error: During pageload undefined no_stack_avail Script: ===

This error usually has no useful data, but it means you called somes API that require a callback and did not define callback function, i.e
in dojo.connect, this.connectClass, dojo.subscribe, etc

this.connectClass('field', 'onclick', 'onField'); // <-- onField is not defined

=== Other errors with "Application loading..." ===

You probably have a syntax error in your Javascript code, and the interface refuses to load.

To find this error, check if there is an error message in the Javascript console (F12).

If there is really nothing on the log, it's probably that the system was unable to load your Javascript because of an syntax error that affect the structure of the Javascript file, typically a missing "}" or a missing "," after a method definition.

If you have "Uncaught ReferenceError: bgagame is not defined" you have major syntax error in your js file, you should see some other clues in the log where the errors is.

=== Unexpected Syntax Error: ===

No further details in the log. When log is filling with some social connect errors.

Possible Reason: Syntax error in of the php script which is loaded before the start, such as gameoptions.inc.php, gameinfos.inc.php and such.

=== Game interface spins in a loop throwing error ===

Errors is something like "Cannot read property 'is_ai' of undefined". Cannot restart the game because cannot access UI to stop.
Likely you get in actplayer state with player id == 0. The only way to fix it is to edit database, globals index == 2 set player id to one of your test dudes
(can copy from row 5 for example).

== Type conversion / juggling errors ==

=== On php side I get a number instead of string I expect ===

$num = 3;
$meeple = "meeple_" + $num; // <-- suppose to be "meeple_3"!

When you switch between JS and PHP it easy to type this and not notice the +. Plus sign (+) in php does not mean string concatenation (in javascript does!),
in php + means integer arithmetic. So change + to . (dot)

=== On php side my string comparison does not work ===

if ($color == '4baae2' || $color == '000000') {
}

Apparently you should not be using '==' in php to compare strings! You should use '==='. The (==) operator will typecast the strings
to numbers then do comparison!
Its not very apparent because usually you can get away with it, but not when strings resemble numbers like hex 'colors'.

=== Integer columns in the database are returned as strings ===

This is normal PHP behavior. All fields are returned as string type, regardless of their actual type in the database. This also applies to global variables accessed via getGameStateValue(), since they are stored in a database table.

You can use type-casting to convert them to the correct type after they come out of the database.

$myValueInt = (int)self::getGameStateValue(GLOBAL_ROUND_NUMBER);

or

$sql = "SELECT my_int_column FROM my_table WHERE my_condition";
$myResult = self::getUniqueValueFromDB($sql); <-- this is a string
$myResultAsInt = (int)$myResult;

https://stackoverflow.com/questions/5323146/mysql-integer-field-is-returned-as-string-in-php

== Other errors ==

=== When I do a move, I got "Move recorded, waiting for update ..." forever ===

"Move recorded" means that your ajaxcall request has been sent to the server and returned normally.

"Waiting for update" means that your client interface is waiting for some notifications from the server that correspond to the move we just did.

If this message stays forever, it is probably that your PHP code does not send any notification when the move happens, which is abnormal. To fix this: add a notifyAllPlayers or a notifyPlayer call in your PHP code.

=== When I do a move, I get "Sending move to server..." the nothing and game resets to state before the move ===

Its possible that server code get into infinite loops or thinks too much, in which case it will timeout and will be aborted without any extra logs (and any db transaction you saw in the log won't be committed). You will usually see "Unable to connect to server" message on console in this case. You have to put more logging into server
to trace where it hangs.

=== Some player action is triggered randomly when I click somewhere on the game area ===

You probably used "dojo.connect" on a null object. In this case, dojo.connect associate the event (ex: "onclick") to the whole game area.

Most of the time it happens in this situation, when my_object element does not exists:
<pre>
dojo.connect( $("my_object"), "onclick", this, function() {
...
}
</pre>

To determine if this is the case, place "alert( $("my_object") )" before the dojo.connect to check if the object exists or not.

=== Javascript does not know how to sum two numbers ===

Be careful when you manipulate integers returned by notifications: most of the time, Javascript considers they are Strings and not Integers.

As a result:
<pre>
var i=1;
i += notif.args.increment; // With notif.args.increment='1'
alert( i ); // i=11 instead of 2 !! Javascript concatenate 2 strings !
</pre>

To solve this, you should use the "toint" function:
<pre>
var i=1;
i += toint( notif.args.increment ); // With notif.args.increment='1'
alert( i ); // i=2 :)
</pre>

=== Javascript: do not use substr with negative numbers ===

To get the last characters of a string, use "slice" instead of "substr" which has a bug on IE:
<pre>
var three_last_characters = string.substr( -3 ); // Wrong
var three_last_characters = string.slice( -3 ); // Correct
</pre>

=== Game "spontaneously" transition to a new state without user input ===

Make sure on php side you have no code after $this->gamestate->nextState(...) code.
Because if you do accidentally have code that goes to another state it will cause another state transition without user interaction.

function selectField($field) {
self::checkAction ( 'selectField' );
if ($field!=0) $this->gamestate->nextState ( 'next' );
$this->gamestate->nextState ( 'last' ); // <-- here is missing else, so it will cause double state transition
}

Tutorial reversi

2020-05-07T20:36:52Z

Brainchild: Fixed some confusion between 'possibleMoves' (the array) and 'possibleMove' (the CSS class). In particular the method onPlayDisc was checking the wrong CSS class name, which meant that clicking a square did nothing.

{{Studio_Framework_Navigation}}

== Introduction ==

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

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

== Create your first game ==

With the initial skeleton of code provided initially, you can already start a game from the BGA Studio. For now, we are going to work with 1 player only. Most of the time it is simpler to proceed with only one player during the early phase of development of your game, as it's easy and fast to start/stop games.

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

== Let it look like Reversi ==

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

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

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

[[File:Board.jpg]]

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

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

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

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

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

Refresh your page. Here's your board:

[[File:reversi1.jpg]]

== Make the squares appears ==

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

Let's modify our template like this:

<pre>
<div id="board">

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

</div>
</pre>

As you can see, we created a "square" block, with 4 variable elements: X, Y, LEFT and TOP. Obviously, we are going to use this block 64 times during page load.

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

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

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

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

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

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

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

Explanations:
* With "position: relative" on board, we ensure square elements are positioned relatively to board.
* For the test, we use a red background color for the square. This is a useful tip to figure out if everything is fine with invisible elements.

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

[[File:reversi2.jpg]]

== The discs ==

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

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

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

<pre>


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

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

[[File:tokens.png]]

Upload this image file "tokens.png" in your "img/" directory.

Important: we are using ONE file for both discs. It's really important that you use a minimum number of graphic files for your game with this "CSS sprite" technique, because it makes the game loading faster and more reliable. [http://www.w3schools.com/css/css_image_sprites.asp Read more about CSS sprites].

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

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

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

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

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

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

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

// Templates

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

</script>
</pre>

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

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

Now, let's create a method in our Javascript code (in the "reversi.js" file) that will make a token appear on the board, using this template:

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

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

At first, with "dojo.place" and "this.format_block" methods, we create a HTML piece of code and insert it as a new child of "tokens" div element.

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

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

Note: note that during all the process, the parent of the new disc HTML element will remain "tokens". placeOnObject and slideToObject methods are only moving the position of elements on screen, and they are not modifying the HTML tree.

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

Note: Probably you'll have to remove the line "self::reattributeColorsBasedOnPreferences( $players, $gameinfos['player_colors'] );".

Now, to test if everything works fine, just add "this.addTokenOnBoard( 2, 2, [player_id] )" in the "setup" Javascript method in reversi.js, and reload the page.

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

[[File:reversi3.jpg]]

== The database ==

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

To design the database model of our game, the best thing to do is to follow the "Go to game database" link at the bottom of our game, to access the database directly with a [http://www.phpmyadmin.net/ PhpMyAdmin] instance.

Then, you can create the tables you need for your table (do not remove existing tables!), and report every SQL command used in your "dbmodel.sql" file.

[[File:reversi4.jpg]]

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

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

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

== Setup the initial game position ==

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

Let's do this:

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

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

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

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

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

Now, we need to make these tokens appear on the client side. To achieve this, the first step is to return the token positions with our "getAllDatas" PHP method (called during each page reload):

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

As you can see, we are using the BGA framework "getObjectListFromDB" method that formats the result of this SQL query in a PHP array with x, y and player attributes.

The last thing we need to do is to process this array client side, and place a disc token on the board for each array item. Of course, we are doing this is our Javascript "setup" method:

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

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

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

Reload... and here we are:

[[File:reversi5.jpg]]

It starts to smell Reversi here...

== The game state machine ==

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

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

[[File:reversi6.jpg]]

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

<pre>
$machinestates = array(

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

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

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

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

);
</pre>

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

... and start a new Reversi game.

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

[[File:reversi7.jpg]]

== The rules ==

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

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

One important thing to keep in mind is the following: making a database query is slow, so please don't load the entire game board with a SQL query multiple time. In our implementation, we load the entire board once at the beginning of "getPossibleMoves", and then pass the board as an argument to all methods.

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

== Display allowed moves ==

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

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

<pre>

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

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

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

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

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

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

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

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

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

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

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

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

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

And here we are:

[[File:reversi8.jpg.jpg]]

== Let's play ==

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

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

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

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

Here's our "onPlayDisc" method below:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

self::DbQuery( $sql );

</pre>

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

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

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

</pre>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

}
</pre>

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

[[File:reversi9.jpg]]

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

== Make the move appear automatically ==

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

And Also the notification to update the scores:

<pre>
notif_newScores: function( notif )
{
for( var player_id in notif.args.scores )
{
var newScore = notif.args.scores[ player_id ];
this.scoreCtrl[ player_id ].toValue( newScore );
}
},
</pre>

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