Board Game Arena - User contributions [en]

Stock

2021-02-05T09:52:52Z

Galehar: Document the selectionClass attribute

{{Studio_Framework_Navigation}}

== Overview ==

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

=== Creation ===

'''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 (an empty div element in your template, with an id).
* width and height (in pixels) for the stock component.

(See ''Hearts'' example above).

'''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:
* {int} type: id of the type to add. You can choose any positive integer. All item types must have distinct IDs.
* {int} 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.
* {string} 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, see image_items_per_row below:

'''image_items_per_row'''
Class member to set number of columns in css sprite (or how many items per row). I.e. if you sprite is 4 cards horizonatall and 6 vertically, you have to set it to 4.
<pre>
// Specify that there are 10 image items per row in images used in "myStockObject" control.
this.myStockObject.image_items_per_row = 4;
</pre>

=== Add/Remove items ===

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

'''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 slides to this HTML element before it disappears.

'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. If you pass noupdate you have 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 slides to this HTML element before it disappears.

'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. If you pass noupdate you have 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 slides to this HTML element before it disappears.

=== Getters ===

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

'''count():'''

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

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

=== Selection ===

'''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). The name of the class can be changed by using the selectionClass attribute. You can also override the default class in the css file for your game but beware of the !important exception.

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.

=== Layout ===

'''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.
Note: it is the same as updateDisplay() without arugment, not sure why there are two methods.

'''updateDisplay(from)'''
Update the display completely (if 'from' is defined: moves new items from this location).

Example code if you change the underlying stock item, or otherwise want to make the stock item refresh:
<pre>
this.myStockControl.updateDisplay();
</pre>

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

Example2:
<pre>
// Be careful with object initialisers with variables, use the bracket notation.
// Item type 1 gets a new weight of 10
var card_type = 1;
this.myStockControl.changeItemsWeight( { [card_type]: 10 } );
</pre>

'''centerItems'''

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

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

'''autowidth'''

Stock does not play well if you attempt to inline-block it with other blocks, to fix that you have to set this flag which will calculate width properly
mystock.autowidth = true;

=== Customize apperance ===

'''extraClasses'''

Can be set to a list of class names (separated by space) on stock object, so when div is created these are added, i.e.

this.playerHand.extraClasses='mycard';

Note that it is the same list for all items.

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

'''onItemDelete'''

Function handler called when div is removed

this.myStock.onItemDelete = (card_div, card_type_id, card_id) => { console.log("card deleted from myStock: "+card_id); };

== 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 (i.e. div id). For example if you want to "reveal" card from player hand and it is not an interface element you can set from to be 'player_board_'+activePlayerId (where activePlayerId is player who played that card).

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

BGA Studio Cookbook

2021-01-22T09:35:09Z

Galehar: Add a method to avoid player misclick with the un-pass button

{{Studio_Framework_Navigation}}

This page is collection of design and implementation recipes for BGA Studio framework.
For tooling and usage recipes see [[Tools and tips of BGA Studio]].
If you have your own recipes feel free to edit this page.

== Visual Effects, Layout and Animation ==

=== Create pieces dynamically (using template) ===

'''Ingredients:''' ggg_ggg.tpl, ggg.js

Note: this method is recommended by BGA guildlines

Declared js template with variables in .tpl file, like this
<pre>
<script type="text/javascript">
// Javascript HTML templates
var jstpl_ipiece = '<div class="${type} ${type}_${color} inlineblock" aria-label="${name}" title="${name}"></div>';
</script>
</pre>

Use it like this in .js file
div = this.format_block('jstpl_ipiece', {
type : 'meeple',
color : 'ff0000',
name : 'Bob',
});

Then you do whatever you need to do with that div, this one specifically design to go to log entries, because it has embedded title (otherwise its a picture only) and no id.

Note: you could have place this variable in js itself, but keeping it in .tpl allows you to have your js code be free of HTML. Normally it never happens but
it is good to strive for it.
Note: you can also use string concatenation, its less readable. You can also use dojo dom object creation api's but its brutally verbose and its more unreadable.

=== Create pieces dynamically (using string concatenation) ===

'''Ingredients:''' ggg.js

Note: Not recommended

<pre>
div = "<div class='meeple "+color+"'></div>";
</pre>
=== Create all pieces statically ===

'''Ingredients:''' ggg_ggg.tpl, ggg.css, ggg.view.php (optional)

* Create ALL game pieces in html template (.tpl)
* ALL pieces should have unique id, and it should be meaningful, i.e. meeple_red_1
* Do not use inline styling
* Id of player's specific pieces should use some sort of 'color' identification, since player id cannot be used in static layout, you can use english color name, hex 6 char value, or color "number" (1,2,3...)
* Pieces should have separated class for its color, type, etc, so it can be easily styled in groups. In example below you now can style all meeples, all red meeples or all red tokens, or all "first" meeples

ggg.tpl:
<pre>
<div id="home_red" class="home_red home">
<div id="meeple_red_1" class="meeple red n1"></div>
<div id="meeple_red_2" class="meeple red n2"></div>
</div>
</pre>

ggg.css:

<pre>
.meeple {
width: 32px;
height: 39px;
background-image: url(img/78_64_stand_meeples.png);
background-size: 352px;
}

.meeple.red {
background-position: 30% 0%;
}
</pre>

* There should be straight forward mapping between server id and js id (or 1:1)
* You place objects in different zones of the layout, and setup css to take care of layout

<pre>
.home .meeple{
display: inline-block;
}
</pre>
* If you need to have a temporary object that look like original you can use dojo.clone (and change id to some temp id)
* If there is lots of repetition or zone grid you can use template generator, but inject style declaration in css instead of inline style for flexibility

Note:
* If you use this model you cannot use premade js components such as Stock and Zone
* You have to use alternative methods of animation (slightly altered) since default method will leave object with inline style attributes which you don't need

=== Use thematic fonts ===

'''Ingredients:''' ggg.css

Sometime game elements use specific fonts of text, if you want to match it up you can load some specific font (IMPORTANT: from some '''free font''' source. See notes below).

[[File:Dragonline_font.png]]

.css
<pre>
/* latin-ext */
@font-face {
font-family: 'Qwigley';
font-style: normal;
font-weight: 400;
src: local('Qwigley'), local('Qwigley-Regular'), url(https://fonts.gstatic.com/s/qwigley/v6/2Dy1Unur1HJoklbsg4iPJ_Y6323mHUZFJMgTvxaG2iE.woff2) format('woff2');
unicode-range: U+0100-024F, U+1E00-1EFF, U+20A0-20AB, U+20AD-20CF, U+2C60-2C7F, U+A720-A7FF;
}
/* latin */
@font-face {
font-family: 'Qwigley';
font-style: normal;
font-weight: normal;
src: local('Qwigley'), local('Qwigley-Regular'), url(https://fonts.gstatic.com/s/qwigley/v6/gThgNuQB0o5ITpgpLi4Zpw.woff2) format('woff2');
unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02C6, U+02DA, U+02DC, U+2000-206F, U+2074, U+20AC, U+2212, U+2215, U+E0FF, U+EFFD, U+F000;
}
@font-face {
font-family: 'Qwigley';
font-style: normal;
font-weight: normal;
src: local('Qwigley'), local('Qwigley-Regular'), url(http://ff.static.1001fonts.net/q/w/qwigley.regular.ttf) format('ttf');
}

.zone_title {
display: inline-block;
position: absolute;
font: italic 32px/32px "Qwigley", cursive;
height: 32px;
width: auto;
}
</pre>

'''NB:''' if you need to include a font that's not available online, an extra action will be needed from an admin. Please include the font file(s) in your img directory, and mention it to admins when requesting your game to be moved to alpha. '''Please remember that the font has to be free, and include a .txt with all appropriate license information about the font.'''
You can look for free fonts (for example) on https://fonts.google.com or https://www.fontsquirrel.com/)

=== Use player color in template ===

'''Ingredients:''' ggg_ggg.tpl, ggg.view.php

.view.php:
<pre>
function build_page($viewArgs) {
// Get players & players number
$players = $this->game->loadPlayersBasicInfos();
$players_nbr = count($players);
/**
* ********* Place your code below: ***********
*/

// Set PCOLOR to the current player color hex
global $g_user;
$cplayer = $g_user->get_id();
if (array_key_exists($cplayer, $players)) { // may be not set if spectator
$player_color = $players [$cplayer] ['player_color'];
} else {
$player_color = 'ffffff'; // spectator
}
$this->tpl ['PCOLOR'] = $player_color;
</pre>

=== Scale to fit for big boards ===

'''Ingredients:''' ggg_ggg.tpl, ggg.js

Lets say you have huge game board, and lets say you want it to be 1400px wide. Besides the board there will be side bar which is 240 and trim.
My display is 1920 wide so it fits, but there is big chance other people won't have that width. What do you do?
Easiest thing I came up with is to scale whole content to fit (everything you declare in .tpl file). Tested or firefox and chrome.

ggg_ggg.tpl:
<pre>
<div id="thething" class="thething" style="width: 1400px;">
... everything else you declare ...
</div>
</pre>

ggg.js:
<pre>
setup : function(gamedatas) {
console.log("Starting game setup");
...
this.interface_min_width = 740;
this.interface_max_width = 1400;
dojo.connect(window, "onresize", this, dojo.hitch(this, "adaptViewportSize"));
},

adaptViewportSize : function() {
var pageid = "page-content";
var nodeid = "thething";

var bodycoords = dojo.marginBox(pageid);
var contentWidth = bodycoords.w;

var browserZoomLevel = window.devicePixelRatio;
//console.log("zoom",browserZoomLevel);
if (contentWidth >= this.interface_max_width || browserZoomLevel >1 || this.control3dmode3d) {
dojo.style(nodeid,'transform','');
return;
}

var percentageOn1 = contentWidth / this.interface_max_width;
dojo.style(nodeid, "transform", "scale(" + percentageOn1 + ")");
},
</pre>

Note: this method does not seems to work to retina resolution displays, if you know better way let me know

=== Dynamic tooltips ===

If you really need a dynamic tooltip you can use this technique. (Only use it if the static tooltips provided by the BGA framework are not sufficient.)

new dijit.Tooltip({
connectId: ["divItemId"],
getContent: function(matchedNode){
return "... calculated ...";
}
});

This is an out-of-the-box djit.Tooltip. It has a ''getContent'' method which is called dynamically.

The string function return becomes the innerHTML of the tooltip, so it can be anything. In this example matchedNode is a dojo node representing dom object with id of "divItemId" but there are more parameters which I am not posting here which allows more sophisticated subnode queries (i.e. you can attach tooltip to all nodes with class or whatever).

[https://dojotoolkit.org/reference-guide/1.10/dijit/Tooltip.html dijit.Tooltip]

It's not part of the BGA API so use at your own risk.

=== Accessing images from js ===

'''Ingredients:''' ggg.js

<pre>
// your game resources

var my_img = '<img src="'+g_gamethemeurl+'img/cards.jpg"/>';

// shared resources
var my_help_img = "<img class='imgtext' src='" + g_themeurl + "img/layout/help_click.png' alt='action' /> <span class='tooltiptext'>" +
text + "</span>";
</pre>

=== Rendering text with players color and proper background ===

'''Ingredients:''' ggg.js

This example actually writes "You" but you can replace this with player name as easily, drop translating function in this case

<pre>
/* Implementation of proper colored You with background in case of white or light colors */

divYou : function() {
var color = this.gamedatas.players[this.player_id].color;
var color_bg = "";
if (this.gamedatas.players[this.player_id] && this.gamedatas.players[this.player_id].color_back) {
color_bg = "background-color:#" + this.gamedatas.players[this.player_id].color_back + ";";
}
var you = "<span style=\"font-weight:bold;color:#" + color + ";" + color_bg + "\">" + __("lang_mainsite", "You") + "</span>";
return you;
},

</pre>

=== Inject icon images in the log ===

Here is an example of what was done for Terra Mystica which is simple and straightforward:

<pre>
//Define the proper message
$message = clienttranslate('${player_name} gets ${power_income} via Structures');
if ($price > 0) {
self::DbQuery("UPDATE player SET player_score = player_score - $price WHERE player_id = $player_id");
$message = clienttranslate('${player_name} pays ${vp_price} and gets ${power_income} via Structures');
}

// Notify
self::notifyAllPlayers( "powerViaStructures", $message, array(
'i18n' => array( ),
'player_id' => $player_id,
'player_name' => self::getUniqueValueFromDb( "SELECT player_name FROM player WHERE player_id = $player_id" ),
'power_tokens' => $power_tokens,
'vp_price' => self::getLogsVPAmount($price),
'power_income' => self::getLogsPowerAmount($power_income),
'newScore' => self::getUniqueValueFromDb( "SELECT player_score FROM player WHERE player_id = $player_id" ),
'counters' => $this->getGameCounters(null),
) );
</pre>

With some functions to have the needed html added inside the substitution variable, such as:

<pre>
function getLogsPowerAmount( $amount ) {
return "<div class='tmlogs_icon' title='Power'><div class='power_amount'>$amount</div></div>";
}
</pre>
Note: injecting html from php is not ideal but easy, if you want more clean solution, use method below but it is a lot more sophisticated.

=== Inject images and styled html in the log ===

'''Ingredients:''' ggg.js, ggg.game.php

So you want nice pictures in the game log. What do you do? The first idea that comes to mind is to send html from php in notifications (see method above).

This is a bad idea for many reasons:

* It's bad architecture. ui elements leak into the server, and now you have to manage the ui in multiple places.
* If you decided to change something in the ui in future version, replay logs for old games and tutorials may not work, since they use stored notifications.
* Log previews for old games become unreadable. (This is the log state before you enter the game replay, which is useful for troubleshooting and game analysis.)
* It's more data to transfer and store in the db.
* It's a nightmare for translators.

So what else can you do? I use this recipe for '''client side log injection''' to intercept log arguments (which come from the server) and replace them with html on the client side.

[[File:clientloginjection.png|left]]

ggg.js

<pre>

/** Override this function to inject html into log items. This is a built-in BGA method. */

/* @Override */
format_string_recursive : function(log, args) {
try {
if (log && args && !args.processed) {
args.processed = true;

// list of special keys we want to replace with images
var keys = ['place_name','token_name'];

for ( var i in keys) {
var key = keys[i];
args[key] = this.getTokenDiv(key, args);

}
}
} catch (e) {
console.error(log,args,"Exception thrown", e.stack);
}
return this.inherited(arguments);
},
</pre>

'''Important:''' In the ''format_string_recursive'' method, the 'args' parameter will only contain arguments passed to it from the notify method in ggg.game.php (see below).

The 'log' parameter is the actual string that is inserted into the logs. You can perform additional js string manipulation on it.

<pre>
getTokenDiv : function(key, args) {
// ... implement whatever html you want here, example from sharedcode.js
var token_id = args[key];
var item_type = getPart(token_id,0);
var logid = "log" + (this.globalid++) + "_" + token_id;
switch (item_type) {
case 'wcube':
var tokenDiv = this.format_block('jstpl_resource_log', {
"id" : logid,
"type" : "wcube",
"color" : getPart(token_id,1),
});
return tokenDiv;
break;
case 'meeple':
if ($(token_id)) {
var clone = dojo.clone($(token_id));

dojo.attr(clone, "id", logid);
this.stripPosition(clone);
dojo.addClass(clone, "logitem");
return clone.outerHTML;
}
break;

default:
break;
}

return "'" + this.clienttranslate_string(this.getTokenName(token_id)) + "'";
},
getTokenName : function(key) {
return this.gamedatas.token_types[key].name; // get name for the key, from static table for example
},
</pre>

Note that in this case the server simply injects token_id as a name, and the client substitutes it for the translated name or the picture.

ggg.game.php:

$this->notifyAllPlayers('playerLog',clienttranslate('Game moves ${token_name}'),['token_name'=>$token_id]);

'''Important:''' As noted above, only arguments actually passed by this method are available to the args parameter received in the client-side ''format_string_recursive'' method.

Sometimes it is the case that you want to pass arguments that are not actually included in the output message. For example, suppose we have a method like this:

$this->notifyAllPlayers('tokenPlaced',clienttranslate('Player placed ${token_name}'),array(
'token_name' => $token_id,
'zone_played' => $zone);

This will output "Player placed ${token_name}" in the log, and if we subscribe to a notification method activated by the "tokenPlaced" event in the client-side code, that method can make use of the 'zone_played' argument. '''But''' 'zone_played' ''will not be available'' in the ''format_string_recursive'' method unless it is actually passed in the log message (i.e., in the string contained inside clienttranslate).

Now if you don't like raw log containing id instead of name but want name, and want substitution, you can use another parameter as id. The problem with that,
it will work at first, but if you reload game using F5 you will loose your additional parameters, why? Because when game reloads it does not actually send same
notifications, it sends special "hitstorical_log" notification where all parameters not listed in the "log" are removed. There is a hack (feature) to circumvent that,
called recursive parameters. I.e. you can send stuff like this:

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

and in format_log_recursive
var key = 'token_name';
if (typeof args[key] == 'string' && typeof args['token_id'] == 'string') {
args[key] = this.getTokenDiv('token_id', args);
}

=== High-Definition Graphics ===

Some users will have screens which can display text and images at a greater resolution than the usual 72 dpi, e.g. the "Retina" screens on the 5k iMac, all iPads, and high-DPI screens on laptops from many manufacturers. If you can get art assets at this size, they will make your game look extra beautiful. You ''could'' just use large graphics and scale them down, but that would increase the download time and bandwidth for users who can't display them. Instead, a good way is to prepare a separate graphics file at exactly twice the size you would use otherwise, and add "@2x" at the end of the filename, e.g. if pieces.png is 240x320, then pieces@2x.png is 480x640.

There are two changes required in order to use the separate graphics files. First in your css, where you use a file, add a media query which overrides the original definition and uses the bigger version on devices which can display them. Ensuring that the "background-size" attribute is set means that the size of the displayed object doesn't change, but only is drawn at the improved dot pitch.
<pre>
.piece {
position: absolute;
background-image: url('img/pieces.png');
background-size:240px 320px;
z-index: 10;
}
@media (-webkit-min-device-pixel-ratio: 2), (min-device-pixel-ratio: 2), (min-resolution: 192dpi)
{
.piece {
background-image: url('img/pieces@2x.png');
}
}
</pre>

Secondly, in your setup function in javascript, you must ensure than only the appropriate one version of the file gets pre-loaded (otherwise you more than waste the bandwidth saved by maintaining the standard-resolution file). Note that the media query is the same in both cases:
<pre>
var isRetina = "(-webkit-min-device-pixel-ratio: 2), (min-device-pixel-ratio: 2), (min-resolution: 192dpi)";
if (window.matchMedia(isRetina).matches)
{
this.dontPreloadImage( 'pieces.png' );
this.dontPreloadImage( 'board.jpg' );
}
else
{
this.dontPreloadImage( 'pieces@2x.png' );
this.dontPreloadImage( 'board@2x.jpg' );
}
</pre>

=== Cool realistic shadow effect with CSS ===

If you wish to make a shadow effect for game pieces that are not rectangle, do not use box-shadow but use filter, which is supported by recent major browsers. This way, you can use the alpha channel of your element to drop a shadow. This even work for transparent backgrounds, so that if you are using the "CSS-sprite" method, it will work!

For instance:

<pre>
.xxx-token {
filter: drop-shadow(0px 0px 1px #000000);
}
</pre>

=== Using the CSS classes from the state machine ===

If you need to hide or show stuff depending on the state of your game, you can of course use javascript, but CSS is hand enough for that. The #overall-content element does change class depending on the game state. For instance, if you are in state ''playerTurn'', it will have the class ''gamestate_playerTurn''.

So now, if you want to show the discard pile only during player turns, you may use:

<pre>
#discard_pile { display: none }
.gamestate_playerTurn #discard_pile { display: block }
</pre>

This can be used if you want to change sizing of elements, position, layout or visual appearance.

=== More readable JS: onEnteringState ===

If you have a lot of states onEnteringState and friends become rather wild, you can do this trick to call some method dynamically.

<pre>

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

// Call appropriate method
var methodName = "onEnteringState_" + stateName;
if (this[methodName] !== undefined) {
console.log('Calling ' + methodName, args.args);
this[methodName](args.args);
}
},

onEnteringState_playerTurn: function(args) { // this is args directly, not args.args
// process
},

onEnteringState_playerSomethingElse: function(args) {
// process
},

</pre>

Note: since its ignores the undefined functions you don't have define function for each state, but on the other hand you cannot make typos.
Same applies to onUpdateActionButtons except you pass 'args' to method, not args.args, and for onLeavingState where you don't pass anything.

== Game Model and Database design ==

=== Database for The euro game ===
Lets say we have a game with workers, dice, tokens, board, resources, money and vp. Workers and dice can be placed in various zones on the board, and you can get resources, money, tokens and vp in your home zone. Also tokens can be flipped or not flipped.

[[File:Madeira board.png]]

Now lets try to map it, we have
* (meeple,zone)
* (die, zone, sideup)
* (resource cube/money token/vp token,player home zone)
* (token, player home zone, flip state)
We can notice that resource and money are uncountable, and don't need to be track individually so we can replace our mapping to
* (resource type/money,player home zone, count)
And vp stored already for us in player table, so we can remove it from that list.

Now when we get to encode it we can see that everything can be encoded as (object,zone,state) form, where object and zone is string and state is integer. The resource mapping is slightly different semantically so you can go with two table, or counting using same table with state been used as count for resources.

So the piece mapping for non-grid based games can be in most case represented by (string: token_key, string: token_location, int: token_state), example of such database schema can be found here: [https://github.com/elaskavaia/bga-sharedcode/blob/master/dbmodel.sql dbmodel.sql] and class implementing access to it here [https://github.com/elaskavaia/bga-sharedcode/blob/master/modules/tokens.php table.game.php].

Variant 1: Minimalistic

CREATE TABLE IF NOT EXISTS `token` (
`token_key` varchar(32) NOT NULL,
`token_location` varchar(32) NOT NULL,
`token_state` int(10),
PRIMARY KEY (`token_key`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

{| class="wikitable"
|+token
! token_key
! token_location
! token_state
|-
|meeple_red_1
|home_red
|0
|-
|dice_black_2
|board_guard
|1
|-
|dice_green_1
|board_action_mayor
|3
|-
|bread
|home_red
|5
|}

Now how we represent resource counters such as bread?
Using same table from we simply add special counter token for bread and use state to indicate the count. Note to keep first column unique we have to add player identification for that counter, i.e. ff0000 is red player.

{| class="wikitable"
|+token
! token_key
! token_location
! token_state
|-
|bread_ff0000
|tableau_ff0000
|5
|}

See php module for this table here https://github.com/elaskavaia/bga-sharedcode/blob/master/modules/tokens.php

Variant 2: Additional resource table, resource count for each player id

CREATE TABLE IF NOT EXISTS `resource` (
`player_id` int(10) unsigned NOT NULL,
`resource_key` varchar(32) NOT NULL,
`resource_count` int(10) signed NOT NULL,
PRIMARY KEY (`player_id`,`resource_key`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

ALTER TABLE resource ADD CONSTRAINT fk_player_id FOREIGN KEY (player_id) REFERENCES player(player_id);

{| class="wikitable"
|+resource
! player_id
! resource_key
! resource_count
|-
|123456
|bread
|5
|}

Variant 3: More normalised

This version is similar to "card" table from hearts tutorial, you can also use exact cards database schema and Deck implementation for most purposes (even you not dealing with cards).

CREATE TABLE IF NOT EXISTS `token` (
`token_id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`token_type` varchar(16) NOT NULL,
`token_arg` int(11) NOT NULL,
`token_location` varchar(32) NOT NULL,
`token_state` int(10),
PRIMARY KEY (`token_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

{| class="wikitable"
|+token
! token_id
! token_type
! token_arg
! token_location
! token_state
|-
|22
|meeple
|123456
|home_123456
|0
|-
|23
|dice
|2
|board_guard
|1
|-
|26
|dice
|1
|board_action_mayor
|3
|-
|49
|bread
|0
|home_123456
|5
|}

Advantages of this would be is a bit more straightforward to do some queries in db, disadvantage its hard to read (as you can compare with previous example, you
cannot just look at say, ah I know what it means). Another questionable advantage is it allows you to do id randomisation, so it hard to do crafted queries to
cheat, the down side of that you cannot understand it either, and handcraft db states for debugging or testing.

=== Database for The card game ===

Lets say you have a standard card game, player have hidden cards in hand, you can draw card from draw deck, play card on tableau and discard to discard pile.
We have to design database for such game.

In real word to "save" the game we take a picture a play area, save cards from it, then put away draw deck, discard and hand of each player separately and mark it, also we will record current scoring (if any) and who's turn was it.

* Framework handles state machine transition, so you don't have to worry about database design for that (i.e. who's turn it is, what phase of the game we are at, you still have to design it but part of state machine step)
* Also framework supports basic player information, color, order around the table, basic scoring, etc, so you don't have to worry about it either
* The only thing you need in our database is state of the "board", which is "where each pieces is, and in what state", or (position,rotation) pair.

Lets see what we have for that:
* The card state is very simple, its usually "face up/face down", "tapped/untapped", "right side up/up side down"
* As position go we never need real coordinates x,y,z. We need to know what "zone" card was, and depending on the zone it may sometimes need an extra "z" or "x" as card order. The zone position usually static or irrelevant.
* So our model is: we have cards, which have some attributes, at any given point in time they belong to a "zone", and can also have order and state
* Now for mapping we should consider what information changes and what information is static, later is always candidate for material file
* For dynamic information we should try to reduce amount of fields we need
** we need at least a field for card, so its one
** we need to know what zone cards belong to, its 2
** and we have possibly few other fields, if you look closely at you game you may find out that most of the zone only need one attribute at a time, i.e. draw pile always have cards face down, hand always face up, also for hand and discard order does not matter at all (but for draw it does matter). So in majority of cases we can get away with one single extra integer field representing state or order
* In real database both card and zone will be integers as primary keys referring to additional tables, but in our case its total overkill, so they can be strings as easily

Variant 1: Minimalistic

<pre>
CREATE TABLE IF NOT EXISTS `card` (
`card_key` varchar(32) unsigned NOT NULL,
`card_location` varchar(32) NOT NULL,
`card_state` int(11) NOT NULL,
PRIMARY KEY (`card_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

Variant 2: More normalised

This version supported by Deck php class, so unless you want to rewrite db access layer go with this one

<pre>
CREATE TABLE IF NOT EXISTS `card` (
`card_id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`card_type` varchar(16) NOT NULL,
`card_type_arg` int(11) NOT NULL,
`card_location` varchar(16) NOT NULL,
`card_location_arg` int(11) NOT NULL,
PRIMARY KEY (`card_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

Note: if you using this schema, some zones/locations have special semantic. The 'hand' location is actually multiple locations - one per player, but player id is encoded as card_location_arg. If 'hand' in your game is ordered, visible or can have some other card states, you cannot use hand location (replacement is hand_<player_id> or hand_<color_id>)

== Game Modules ==

=== Including your own JavaScript module ===
'''Ingredients:''' ggg.js, modules/ggg_other.js

* Create ggg_other.js in modules/ folder and sync
* Modify ggg.js to include it

define([ "dojo", "dojo/_base/declare", "ebg/core/gamegui", "ebg/counter",
// load my own module!!!
g_gamethemeurl + "modules/ggg_other.js" ], function(dojo,
declare) {

=== Including your own PHP module ===
'''Ingredients:''' ggg.game.php, modules/ggg_other.php

* Create ggg_other.php in modules/ folder and sync
* Modify ggg.game.php to include it

require_once ('modules/ggg_other.php');

=== Avoiding code in dojo declare style ===
Dojo class declarations are rather bizzare and do not work with most IDEs.
If you want to write in plain JS with classes you can stub all the dojo define/declare stuff
and hook your class into that, so class if outside of this mess.

NOTE: this technique is for experienced developers, do not try it if you do not understand
the consequences.

This is complete example of game .js class
<pre>
// Testla is game name is has to be changed
class Testla {
constructor(game) {
console.log('game constructor');
this.game = game;
this.varfoo = new MyFoo(); // this example of class from custom module
}

setup(gamedatas) {
console.log("Starting game setup", this.varfoo);
this.gamedatas = gamedatas;
this.dojo.create("div", { class: 'whiteblock', innerHTML: _("hello") }, 'thething');
console.log("Ending game setup");
};
onEnteringState(stateName, args) {
console.log('onEnteringState : ' + stateName, args);
this.game.addActionButton('b1',_('Click Me'), (e)=>this.onButtonClick(e));
};
onLeavingState(stateName) {
console.log('onLeavingState : ' + stateName, args);
};
onUpdateActionButtons(stateName, args) {
console.log('onUpdateActionButtons : ' + stateName, args);
};
onButtonClick(event) {
console.log('onButtonClick',event);
};
};

define([
"dojo", "dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
g_gamethemeurl + '/modules/foo.js' // custom module if needed
],
function(dojo, declare) {
// testla is game name is has to be changed
return declare("bgagame.testla", ebg.core.gamegui, {
constructor: function() {
this.xapp = new Testla(this);
this.xapp.dojo = dojo;
},
setup: function(gamedatas) {
this.xapp.setup(gamedatas);
},
onEnteringState: function(stateName, args) {
this.xapp.onEnteringState(stateName, args.args);
},
onLeavingState: function(stateName) {
this.xapp.onLeavingState(stateName, args);
},
onUpdateActionButtons: function(stateName, args) {
this.xapp.onUpdateActionButtons(stateName, args);
},
});
});

</pre>

== Assorted Stuff ==

=== Out-of-turn actions: Un-pass ===

'''Ingredients:''' ggg.js, ggg.game.php, ggg.action.php, states.inc.php

In multiplayer game sometimes players passes but than they think more and want to un-Pass and redo their choice.
To re-active a player who passes some trickery required.

Define a special action that does how and hook it up.

In states.inc.php add an action to mmultipleactiveplayer state to "unpass", lets call it "actionCancel"

In ggg.action.php add action hook
public function actionCancel() {
self::setAjaxMode();
$this->game->actionCancel();
self::ajaxResponse();
}

In ggg.game.php add action handler
function actionCancel() {
$this->gamestate->checkPossibleAction('actionCancel');
$this->gamestate->setPlayersMultiactive(array ($this->getCurrentPlayerId() ), 'error', false);
}

Finally to call this in client ggg.js you would do something like:
<pre>
onUpdateActionButtons: function(stateName, args) {
if (this.isCurrentPlayerActive()) {
// ...
} else if (!this.isSpectator) { // player is NOT active but not spectatoe
switch (stateName) {
case 'playerTurnMuliPlayerState':
this.addActionButton('button_unpass', _('Oh no!'), 'onUnpass');
break;
}
}
}

onUnpass: function(e) {
this.ajaxcall("/" + this.game_name + "/" + this.game_name + "/actionCancel.html", {}, this); // no checkAction!
}
</pre>
Although be careful that if the turn comes back to the player while he is about to click cancel, the action buttons will be updated and the player will misclick which can be quite frustrating. To avoid this, move the cancel button to another position, like to the left of pagemaintitletext:
dojo.place('button_unpass', 'pagemaintitletext', 'before');
Being out of the generalactions div, it won't be automatically destroyed like normal buttons, so you'll have to handle that yourself in onLeavingState. You might also want to change the button color to red (blue buttons for active player only, red buttons also for inactive players?)

=== Multi Step Interactions: Select Worker/Place Worker - Using Selection ===

'''Ingredients:''' ggg.js

Simple way to implement something like that without extra states is to use "selection" mechanism. When user click on worker add some sort of class into that element i.e. 'selected' (which also have to have some indication by css i.e. outline).

Than user can click on placement zone, you can use dojo.query for "selected" element and use it along with zone id to send data to server. If proper worker is not selected yet can give a error message using this.showMessage(...) function.

Extra code required to properly cleanup selection between states

=== Multi Step Interactions: Select Worker/Place Worker - Using Client States ===

'''Ingredients:''' ggg.js

I don't think its documented feature but there is a way to do client-only states, which is absolutely wonderful for few reasons
* When player interaction is two step process, such as select worker, place worker, or place worker, pick one of two resources of your choice
* When multi-step process can result of impossible situation and has to be undone (by rules)
* When multi-step process is triggered from multiple states (such as you can do same thing as activated card action, pass action or main action)

So lets do Select Worker/Place Worker

Define your server state as usual, i.e. playerMainTurn -> "You must pick up a worker".
Now define a client state, we only need "name" and "descriptionmyturn", lets say "client_playerPicksLocation". Always prefix names of client state with "client_" to avoid confusion. Now we have to do the following:
* Have a handler for onUpdateActionButtons for playerMainTurn to activate all possible workers he can pick
* When player clicks workers, remember the worker in one of the members of the main class, I usually use one called this.clientStateArgs.
* Transition to new client state
onWorker: function(e) {
var id = event.currentTarget.id;
dojo.stopEvent(event);
... // do validity checks
this.clientStateArgs.worker_id = id;
this.setClientState("client_playerPicksLocation", {
descriptionmyturn : "${you} must select location",
});
}
* Have a handler for onUpdateActionButtons for client_playerPicksLocation to activate all possible locations this worker can go AND add Cancel button (see below)
* Have a location handler which will eventually send a server request, using stored this.clientStateArgs.worker_id as worker id
* The cancel button should call a method to restore server state, also if you doing it for more than one state you can add this universally using this.on_client_state check

if (this.isCurrentPlayerActive()) {
if (this.on_client_state && !$('button_cancel')) {
this.addActionButton('button_cancel', _('Cancel'), dojo.hitch(this, function() {
this.restoreServerGameState();
}));
}
}
Note: usually I call my own function call this.cancelLocalStateEffects() which will do more stuff first then call restoreServerGameState(), same function is usually needs to be called when server request has failed (i.e. invalid move)

Note: If you need more than 2 steps, you may have to do client side animation to reflect the new state, which gets trickier because you have to undo that also on cancellation.

Code is available here [https://github.com/elaskavaia/bga-sharedcode/blob/master/sharedcode.js sharedcode.js] (its using playerTurnPlayCubes and client_selectCubeLocation).

Practical debugging

2021-01-21T16:19:07Z

Galehar: Add the automated version by quietmint

{{Studio_Framework_Navigation}}

This page gives you practical tips to debug your game during development. Don't hesitate to share your difficulties with us so that we can improve this section.

== Tools ==

To work on BGA Studio, we recommend that you use [http://www.google.com/chrome Google Chrome] as it's currently the fastest browser for the BGA platform, and it's available for all OSes.

Another reason to use Chrome is that it embeds all the tools you need to work on BGA Studio. You can see them by pressing "F12" or from the menu ("Tools > Development tools").

A good practice is to use a second browser to develop the game, in order to verify that your game is working fine on this browser too.

To debug with Firefox browser, we advise you to use these 2 extensions:
* [https://addons.mozilla.org/firefox/addon/firebug/ Firebug]
* [https://addons.mozilla.org/firefox/addon/web-developer/ Web developer]

To debug with other browsers (IE, Edge, Opera), we advise you to use one of the most recent versions. Latest versions of the browser will likely have better development tools than the previous ones...

== General tip for debugging ==

In general for debugging, think of using the '[[Tools_and_tips_of_BGA_Studio#Save_.26_restore_state|save & restore]] state' functionality. It enables you to save the state of your game just before the issue you are investigating, then come back to that point with one click as many times as needed to understand what is going wrong.

You can save up to 3 different states.

== Debugging my game when it cannot start ==

If your game won't start because of an error, you are probably in one of these situations:
* There is a SQL error in your dbmodel.sql file.
* You have a syntax error in your PHP file.
* Your PHP "setup" - or any method used during the game initial states - generates an exception.

If the error is not explicitly displayed when you click on "Express start", you should check the "Gameserver error log" as per [[Studio logs]].
More cases of why game can't start are described on the [[Troubleshooting]] page.

== Debugging my PHP game logic (or my view) ==

=== Add traces to your code ===

You can use the following functions in your game to add server side logging:

'''self::dump( 'name_of_variable', $variable );''' // dump variable, like var_dump but in the log debug level logging, goes to [[Studio_logs|BGA request&SQL logs]]

'''self::debug( $message );''' // debug level logging, goes to [[Studio_logs|BGA request&SQL logs]]

'''self::trace( $message );''' // info level logging, goes to [[Studio_logs|BGA request&SQL logs]]

'''self::warn( $message );''' // warning level logging, goes to [[Studio_logs#BGA_unexpected_exceptions_logs|BGA unexpected exceptions log]]

'''self::error( $message );''' // error level logging, goes to [[Studio_logs#BGA_unexpected_exceptions_logs|BGA unexpected exceptions log]]

Check [[Studio logs]] for more details on how to access your logs.

This can be useful when you need to follow the flow of your code and not just stop it to see how it goes at some point.

Only the error log level will appear in production. This level should be used only for critical problems.
Other levels will show only in the development environment and can be used as you see fit.

'''WARNING''': tracing does not work in constructor, setupNewGame and game states immediately following starting state (not sure why). Use other method below in this case.

=== Call php functions from chat ===

This is best feature ever, you can call individual function in your game.php from chat window, see details
at https://en.doc.boardgamearena.com/Tools_and_tips_of_BGA_Studio#Run_PHP_functions_from_the_chat

=== Dump data and die ===

Most of the time, debugging PHP is quite easy. Here's what I do when I want to develop/debug some game logic that is triggered by some game action:

* At first, I make sure that I can reproduce the needed game situation with one click. To do this, I use the "[[Tools_and_tips_of_BGA_Studio#Save_.26_restore_state|save & restore]]" function.
* Another possibility for this is to place a '''die('ok');''' PHP statement right after the PHP I am developing/debugging. This way, I make sure that every request will fail and then nothing will be committed to the database.
* Then, I use the '''var_dump''' function to dump PHP variables and check what's wrong, until it works.

Example:
<pre>

// (...my code to debug)

var_dump( $my_variable );
die('ok');

// (...my code to debug)

</pre>

Now since this text will be returned back to client it will usually choke on this, but you can actually see it better if you wrap it some html, i.e.
<pre>
echo "<pre>";
var_dump( $my_variable );
echo "</pre>";
</pre>

=== Debug at home ===

If you develop some complex logic it is better sometimes to stub all external calls and debug it locally using command line or IDE debugger for php.
You can get some basic stubs here https://github.com/elaskavaia/bga-sharedcode/raw/master/misc/module/table/table.game.php

=== Debugging setupNewGame ===

This is separate section because tracing method do not work in this function.
Recommended way to debug it - leave template code that deal with player and setting active player, add your own call
to
$this->initTables();
This will be your own function which you will be changing, so you don't touch setupNewGame anymore.

Remember that this function cannot send notification or query active or current player.

Create a code for this function, and if it does not work run it from the chat window of the just created game (i.e. 'initTables()' without quotes). That way you can see debug output!
The only trick is you have to clear all your tables in the begging so when you run it multiple times your db does not puke.
If your game does not start at all - do not even call it from setupNewGame, comment it out and only call from chat window until it works.
Don't forget you can also look at tables in db using php-admin tool (link at the bottom of the game table in studio), it is just painfully slow.

The same problem exists if you game state immediately follow starting state, in this case create a dummy player state in which player just press OK that will transition
to you game state, after you done debugging it remove the state and shortcut the transition to your game state.

== Debugging my HTML/CSS layout ==

Example situations

* Why doesn't my game element show up in the interface?
* Why hasn't my CSS property been applied to this element?
* Why is this game element displayed at this position?

A useful tip when an element does not show up in the interface is to give it a red background:
<pre>
#my_element {
... some CSS definitions ...
background-color: red;
}
</pre>

This way, you know if the element is not visible because of some CSS property or because of something else.

Another tip: sometimes, changing a CSS property has no visible effect on your interface. In that case, add a "display:none" property. If your element does not disappear, the bug probably comes from your CSS selector and not from your CSS property.

Using Chrome "Elements" tab (the first one), you can:
* See the CURRENT HTML of your page. Remember that the classical "show page source" is inefficient with BGA as you are modifying the page source with your Javascript code.
* Using the "magnifying glass", you can click on any part of your game interface and check its HTML code and associated CSS styles.
* You can even modify directly some CSS properties and see how it looks immediately in the game interface.

When changing css you have to force reload (Ctrl+R). But it also reloads all images which is long, if you want it faster you can define this function in js file, and call it from Browser js console
<pre>
function reloadCss() {
var links = document.getElementsByTagName("link");
for (var cl in links) {
var link = links[cl];
if (link.rel === "stylesheet")
link.href += "?";
}
}
</pre>
=== Debugging Toolips CSS/Layout ===

To inspect tooltip you need to pin it so it does not disappear.
Best way to do that is to inspect element which you have tooltip for, and in dev tools (or similar) force state to hover, i.e. select ":hov" icon and select :hover checkbox.

If this does not work: open the console (dev tools) large enough window, hover to make the tooltip appear and alt + tab to focus the console that will cover the tooltip. That way the onmouseout will never be triggered.

=== Debugging my Javascript game interface logic ===

Compared to PHP debugging, Javascript debugging can sometimes be painful.

Here are some tips to make your life easier while developing and debugging Javascript:

=== Do complex things on the PHP side ===

The most frequent case is the following: you want to compute possible moves in a game situation. Doing it in Javascript is a nightmare. Do it in PHP, and transfer the results to your client interface using the "args" game state property.

Note: See the Reversi tutorial for an example.

=== Add traces in your code ===

You can use the following:

'''console.log( variable_to_inspect )'''

It will give you the object structure of the variable in the Javascript console, without blocking the execution.

It's often a good idea to precede this call with a console.log( '### HERE ###' ); to find more easily the appropriate line in the console log.

'''alert( variable_to_inspect )'''

It will popup what you wish and pause the execution until you click ok.

This won't be useful for complex structures; only native types will be plainly displayed. But this is sometimes useful just with messages to make sure which way the execution goes.

=== Use Browser Debugger (e.g. Chrome) ===

Modern browsers also allow you to put breakpoints in your js code.

This will stop code execution on that line and will launch the JavaScript debugger.

In Chrome, to add a breakpoint: add a line to your .js file

<pre>debugger; </pre>

Refresh the page F5, and make sure you have the Developer tools window open, press F12.
When the break-point is hit you can then step through your code and visualise variables, etc.

== Online format checkers ==
Copy and paste code for a quick code sanity check like the right number of brackets.

PHP: [https://phpcodechecker.com/ https://phpcodechecker.com/]

JS: [http://esprima.org/demo/validate.html http://esprima.org/demo/validate.html]

Checks for proper attributes values and browser's compatibility

CSS: http://jigsaw.w3.org/css-validator/

== Some frequent errors ==

See [[Troubleshooting]].

== Get the database matching a bug report ==

When a player creates a bug report in production, a snapshot of the game database is taken. You can get access to this snapshot from the studio by following the steps below:
* Create a table in the studio with the same game and number of players as the table for which the report has been written. Launch this table.
* Open another tab on the studio and go to "Manage game" page for your project (you have to be admin for this project)
* In the "Errors in production" section, fill up the fields "Bug report ID" (this is the ID of the bug report in production) and "Studio table ID" (this is the ID of the table you created above) then click the "⇨ Load bug report state into this table save slot #1" button.
* If the snapshot is correctly retrieved, you see a "Done!" message.
* Go back to the tab with your studio table and click "Load 1".
* The page refreshes automatically and is broken. This is normal, as the player ids from the snapshot are the player ids of the production, not those of the studio. We'll need to update them.
** '''Important note:''' if you see a "Done!" message but clicking "Load 1" doesn't bring any change, it's that the snapshot is unfortunately not available (most likely because the bug report was declared too long after the game ended and the database had already been garbage collected to reclaim space).
* Click on the "Go to game database" button
* For each table using player_ids, you'll need to update the player_ids from the production to use the player_ids from the studio. You can see the player_ids from the table page before entering the game by hovering over the player names.
* Tables to update:
** player
** global (value with ID 2 is the active player)
** stats
** tables specific to your schema that use player_ids
* If your changes to player_ids are not taken into account, it may be a cache problem: use the "Clear PHP cache" button on your "Manage game" page.
* Then you should be able to play with the same state of the game as when the report was created in production.
* If the game has ended, you can place it again in the game state you want to debug by setting the value with ID 1 in the global table to the appropriate state value, and the value with ID 2 to the player you want active).
*
* Below is an example php function you may want to make. You can call this function from the chat window: LoadDebug()
* change instances of 2308257, and 2308258 to you own BGA Studio logins YourLogin0 and YourLogin1
* change $id0 and $id1 to the player_ids from the table you want to debug, and have recently imported.
* Before you load Slot1, open a second tab with the table, because after loading the slot, that tab will be unusable. In the second tab you can call LoadDebug() in the chat window

<pre>
public function LoadDebug()
{
// These are the id's from the BGAtable I need to debug.
$ids = [
86107517,
86872172,
85086097,
84380410,
11000525
];

// Id of the first player in BGA Studio
$sid = 2296755;

foreach ($ids as $id) {
// basic tables
self::DbQuery("UPDATE player SET player_id=$sid WHERE player_id = $id" );
self::DbQuery("UPDATE global SET global_value=$sid WHERE global_value = $id" );
self::DbQuery("UPDATE stats SET stats_player_id=$sid WHERE stats_player_id = $id" );

// 'other' game specific tables. example:
// tables specific to your schema that use player_ids
self::DbQuery("UPDATE card SET card_location_arg=$sid WHERE card_location_arg = $id" );

++$sid;
}
}
</pre>

=== Fully automated version ===
Thanks to quietmint for [https://boardgamearena.com/forum/viewtopic.php?f=12&t=16454#p63167 coming up] with that!

Add loadBug() and loadBugSQL() to game.php:
<code>
/*
* loadBug: in studio, type loadBug(20762) into the table chat to load a bug report from production
* client side JavaScript will fetch each URL below in sequence, then refresh the page
*/
public function loadBug($reportId)
{
$db = explode('_', self::getUniqueValueFromDB("SELECT SUBSTRING_INDEX(DATABASE(), '_', -2)"));
$game = $db[0];
$tableId = $db[1];
self::notifyAllPlayers('loadBug', "Trying to load <a href='https://boardgamearena.com/bug?id=$reportId' target='_blank'>bug report $reportId</a>", [
'urls' => [
// Emulates "load bug report" in control panel
"https://studio.boardgamearena.com/admin/studio/getSavedGameStateFromProduction.html?game=$game&report_id=$reportId&table_id=$tableId",

// Emulates "load 1" at this table
"https://studio.boardgamearena.com/table/table/loadSaveState.html?table=$tableId&state=1",

// Calls the function below to update SQL
"https://studio.boardgamearena.com/1/$game/$game/loadBugSQL.html?table=$tableId&report_id=$reportId",

// Emulates "clear PHP cache" in control panel
// Needed at the end because BGA is caching player info
"https://studio.boardgamearena.com/admin/studio/clearGameserverPhpCache.html?game=$game",
]
]);
}

/*
* loadBugSQL: in studio, this is one of the URLs triggered by loadBug() above
*/
public function loadBugSQL($reportId)
{
$studioPlayer = self::getCurrentPlayerId();
$players = self::getObjectListFromDb("SELECT player_id FROM player", true);

// Change for your game
// We are setting the current state to match the start of a player's turn if it's already game over
$sql = [
"UPDATE global SET global_value=" . ST_MOVE . " WHERE global_id=1 AND global_value=" . ST_BGA_GAME_END
];
foreach ($players as $pId) {
// All game can keep this SQL
$sql[] = "UPDATE player SET player_id=$studioPlayer WHERE player_id=$pId";
$sql[] = "UPDATE global SET global_value=$studioPlayer WHERE global_value=$pId";
$sql[] = "UPDATE stats SET stats_player_id=$studioPlayer WHERE stats_player_id=$pId";

// Change the below SQL to update the specific tables for your game
$sql[] = "UPDATE card SET card_location_arg=$studioPlayer WHERE card_location_arg=$pId";
$sql[] = "UPDATE piece SET player_id=$studioPlayer WHERE player_id=$pId";
$sql[] = "UPDATE log SET player_id=$studioPlayer WHERE player_id=$pId";
$sql[] = "UPDATE log SET action_arg=REPLACE(action_arg, $pId, $studioPlayer)";

// This could be improved, it assumes you had sequential studio accounts before loading
// e.g., quietmint0, quietmint1, quietmint2, etc. are at the table
$studioPlayer++;
}
$msg = <nowiki>"<b>Loaded <a href='https://boardgamearena.com/bug?id=$reportId' target='_blank'>bug report $reportId</a></b><hr><ul><li>" . implode(';</li><li>', $sql) . ';</li></ul>';</nowiki>
self::warn($msg);
self::notifyAllPlayers('message', $msg, []);

foreach ($sql as $q) {
self::DbQuery($q);
}
self::reloadPlayersBasicInfos();
}</code>

Add loadBugSQL() to actions.php
<code>
public function loadBugSQL()
{
self::setAjaxMode();
$reportId = (int) self::getArg('report_id', AT_int, true);
$this->game->loadBugSQL($reportId);
self::ajaxResponse();
}</code>

Add loadBug notification handler to game.js:
<code>
notif_loadBug: function (n) {
function fetchNextUrl() {
var url = n.args.urls.shift();
console.log('Fetching URL', url);
dojo.xhrGet({
url: url,
load: function (success) {
// This could be improved, I don't check the response for errors
console.log('Success for URL', url, success);
if (n.args.urls.length > 0) {
fetchNextUrl();
} else {
console.log('Done, reloading page');
window.location.reload();
}
}
});
}

console.log('Notif: load bug', n.args);
fetchNextUrl();
},</code>

That's it!

Practical debugging

2020-12-29T09:55:32Z

Galehar: Improve the LoadDebug function

{{Studio_Framework_Navigation}}

This page gives you practical tips to debug your game during development. Don't hesitate to share your difficulties with us so that we can improve this section.

== Tools ==

To work on BGA Studio, we recommend that you use [http://www.google.com/chrome Google Chrome] as it's currently the fastest browser for the BGA platform, and it's available for all OSes.

Another reason to use Chrome is that it embeds all the tools you need to work on BGA Studio. You can see them by pressing "F12" or from the menu ("Tools > Development tools").

A good practice is to use a second browser to develop the game, in order to verify that your game is working fine on this browser too.

To debug with Firefox browser, we advise you to use these 2 extensions:
* [https://addons.mozilla.org/firefox/addon/firebug/ Firebug]
* [https://addons.mozilla.org/firefox/addon/web-developer/ Web developer]

To debug with other browsers (IE, Edge, Opera), we advise you to use one of the most recent versions. Latest versions of the browser will likely have better development tools than the previous ones...

== General tip for debugging ==

In general for debugging, think of using the '[[Tools_and_tips_of_BGA_Studio#Save_.26_restore_state|save & restore]] state' functionality. It enables you to save the state of your game just before the issue you are investigating, then come back to that point with one click as many times as needed to understand what is going wrong.

You can save up to 3 different states.

== Debugging my game when it cannot start ==

If your game won't start because of an error, you are probably in one of these situations:
* There is a SQL error in your dbmodel.sql file.
* You have a syntax error in your PHP file.
* Your PHP "setup" - or any method used during the game initial states - generates an exception.

If the error is not explicitly displayed when you click on "Express start", you should check the "Gameserver error log" as per [[Studio logs]].
More cases of why game can't start are described on the [[Troubleshooting]] page.

== Debugging my PHP game logic (or my view) ==

=== Add traces to your code ===

You can use the following functions in your game to add server side logging:

'''self::dump( 'name_of_variable', $variable );''' // dump variable, like var_dump but in the log debug level logging, goes to [[Studio_logs|BGA request&SQL logs]]

'''self::debug( $message );''' // debug level logging, goes to [[Studio_logs|BGA request&SQL logs]]

'''self::trace( $message );''' // info level logging, goes to [[Studio_logs|BGA request&SQL logs]]

'''self::warn( $message );''' // warning level logging, goes to [[Studio_logs#BGA_unexpected_exceptions_logs|BGA unexpected exceptions log]]

'''self::error( $message );''' // error level logging, goes to [[Studio_logs#BGA_unexpected_exceptions_logs|BGA unexpected exceptions log]]

Check [[Studio logs]] for more details on how to access your logs.

This can be useful when you need to follow the flow of your code and not just stop it to see how it goes at some point.

Only the error log level will appear in production. This level should be used only for critical problems.
Other levels will show only in the development environment and can be used as you see fit.

'''WARNING''': tracing does not work in constructor, setupNewGame and game states immediately following starting state (not sure why). Use other method below in this case.

=== Call php functions from chat ===

This is best feature ever, you can call individual function in your game.php from chat window, see details
at https://en.doc.boardgamearena.com/Tools_and_tips_of_BGA_Studio#Run_PHP_functions_from_the_chat

=== Dump data and die ===

Most of the time, debugging PHP is quite easy. Here's what I do when I want to develop/debug some game logic that is triggered by some game action:

* At first, I make sure that I can reproduce the needed game situation with one click. To do this, I use the "[[Tools_and_tips_of_BGA_Studio#Save_.26_restore_state|save & restore]]" function.
* Another possibility for this is to place a '''die('ok');''' PHP statement right after the PHP I am developing/debugging. This way, I make sure that every request will fail and then nothing will be committed to the database.
* Then, I use the '''var_dump''' function to dump PHP variables and check what's wrong, until it works.

Example:
<pre>

// (...my code to debug)

var_dump( $my_variable );
die('ok');

// (...my code to debug)

</pre>

Now since this text will be returned back to client it will usually choke on this, but you can actually see it better if you wrap it some html, i.e.
<pre>
echo "<pre>";
var_dump( $my_variable );
echo "</pre>";
</pre>

=== Debug at home ===

If you develop some complex logic it is better sometimes to stub all external calls and debug it locally using command line or IDE debugger for php.
You can get some basic stubs here https://github.com/elaskavaia/bga-sharedcode/raw/master/misc/module/table/table.game.php

=== Debugging setupNewGame ===

This is separate section because tracing method do not work in this function.
Recommended way to debug it - leave template code that deal with player and setting active player, add your own call
to
$this->initTables();
This will be your own function which you will be changing, so you don't touch setupNewGame anymore.

Remember that this function cannot send notification or query active or current player.

Create a code for this function, and if it does not work run it from the chat window of the just created game (i.e. 'initTables()' without quotes). That way you can see debug output!
The only trick is you have to clear all your tables in the begging so when you run it multiple times your db does not puke.
If your game does not start at all - do not even call it from setupNewGame, comment it out and only call from chat window until it works.
Don't forget you can also look at tables in db using php-admin tool (link at the bottom of the game table in studio), it is just painfully slow.

The same problem exists if you game state immediately follow starting state, in this case create a dummy player state in which player just press OK that will transition
to you game state, after you done debugging it remove the state and shortcut the transition to your game state.

== Debugging my HTML/CSS layout ==

Example situations

* Why doesn't my game element show up in the interface?
* Why hasn't my CSS property been applied to this element?
* Why is this game element displayed at this position?

A useful tip when an element does not show up in the interface is to give it a red background:
<pre>
#my_element {
... some CSS definitions ...
background-color: red;
}
</pre>

This way, you know if the element is not visible because of some CSS property or because of something else.

Another tip: sometimes, changing a CSS property has no visible effect on your interface. In that case, add a "display:none" property. If your element does not disappear, the bug probably comes from your CSS selector and not from your CSS property.

Using Chrome "Elements" tab (the first one), you can:
* See the CURRENT HTML of your page. Remember that the classical "show page source" is inefficient with BGA as you are modifying the page source with your Javascript code.
* Using the "magnifying glass", you can click on any part of your game interface and check its HTML code and associated CSS styles.
* You can even modify directly some CSS properties and see how it looks immediately in the game interface.

When changing css you have to force reload (Ctrl+R). But it also reloads all images which is long, if you want it faster you can define this function in js file, and call it from Browser js console
<pre>
function reloadCss() {
var links = document.getElementsByTagName("link");
for (var cl in links) {
var link = links[cl];
if (link.rel === "stylesheet")
link.href += "?";
}
}
</pre>
=== Debugging Toolips CSS/Layout ===

To inspect tooltip you need to pin it so it does not disappear.
Best way to do that is to inspect element which you have tooltip for, and in dev tools (or similar) force state to hover, i.e. select ":hov" icon and select :hover checkbox.

If this does not work: open the console (dev tools) large enough window, hover to make the tooltip appear and alt + tab to focus the console that will cover the tooltip. That way the onmouseout will never be triggered.

=== Debugging my Javascript game interface logic ===

Compared to PHP debugging, Javascript debugging can sometimes be painful.

Here are some tips to make your life easier while developing and debugging Javascript:

=== Do complex things on the PHP side ===

The most frequent case is the following: you want to compute possible moves in a game situation. Doing it in Javascript is a nightmare. Do it in PHP, and transfer the results to your client interface using the "args" game state property.

Note: See the Reversi tutorial for an example.

=== Add traces in your code ===

You can use the following:

'''console.log( variable_to_inspect )'''

It will give you the object structure of the variable in the Javascript console, without blocking the execution.

It's often a good idea to precede this call with a console.log( '### HERE ###' ); to find more easily the appropriate line in the console log.

'''alert( variable_to_inspect )'''

It will popup what you wish and pause the execution until you click ok.

This won't be useful for complex structures; only native types will be plainly displayed. But this is sometimes useful just with messages to make sure which way the execution goes.

=== Use Browser Debugger (e.g. Chrome) ===

Modern browsers also allow you to put breakpoints in your js code.

This will stop code execution on that line and will launch the JavaScript debugger.

In Chrome, to add a breakpoint: add a line to your .js file

<pre>debugger; </pre>

Refresh the page F5, and make sure you have the Developer tools window open, press F12.
When the break-point is hit you can then step through your code and visualise variables, etc.

== Online format checkers ==
Copy and paste code for a quick code sanity check like the right number of brackets.

PHP: [https://phpcodechecker.com/ https://phpcodechecker.com/]

JS: [http://esprima.org/demo/validate.html http://esprima.org/demo/validate.html]

Checks for proper attributes values and browser's compatibility

CSS: http://jigsaw.w3.org/css-validator/

== Some frequent errors ==

See [[Troubleshooting]].

== Get the database matching a bug report ==

For a way to automate the below steps, see this post: https://boardgamearena.com/forum/viewtopic.php?f=12&t=16454#p63167

---

When a player creates a bug report in production, a snapshot of the game database is taken. You can get access to this snapshot from the studio by following the steps below:
* Create a table in the studio with the same game and number of players as the table for which the report has been written. Launch this table.
* Open another tab on the studio and go to "Manage game" page for your project (you have to be admin for this project)
* In the "Errors in production" section, fill up the fields "Bug report ID" (this is the ID of the bug report in production) and "Studio table ID" (this is the ID of the table you created above) then click the "⇨ Load bug report state into this table save slot #1" button.
* If the snapshot is correctly retrieved, you see a "Done!" message.
* Go back to the tab with your studio table and click "Load 1".
* The page refreshes automatically and is broken. This is normal, as the player ids from the snapshot are the player ids of the production, not those of the studio. We'll need to update them.
** '''Important note:''' if you see a "Done!" message but clicking "Load 1" doesn't bring any change, it's that the snapshot is unfortunately not available (most likely because the bug report was declared too long after the game ended and the database had already been garbage collected to reclaim space).
* Click on the "Go to game database" button
* For each table using player_ids, you'll need to update the player_ids from the production to use the player_ids from the studio. You can see the player_ids from the table page before entering the game by hovering over the player names.
* Tables to update:
** player
** global (value with ID 2 is the active player)
** stats
** tables specific to your schema that use player_ids
* If your changes to player_ids are not taken into account, it may be a cache problem: use the "Clear PHP cache" button on your "Manage game" page.
* Then you should be able to play with the same state of the game as when the report was created in production.
* If the game has ended, you can place it again in the game state you want to debug by setting the value with ID 1 in the global table to the appropriate state value, and the value with ID 2 to the player you want active).
*
* Below is an example php function you may want to make. You can call this function from the chat window: LoadDebug()
* change instances of 2308257, and 2308258 to you own BGA Studio logins YourLogin0 and YourLogin1
* change $id0 and $id1 to the player_ids from the table you want to debug, and have recently imported.
* Before you load Slot1, open a second tab with the table, because after loading the slot, that tab will be unusable. In the second tab you can call LoadDebug() in the chat window

<pre>
public function LoadDebug()
{
// These are the id's from the BGAtable I need to debug.
$ids = [
86107517,
86872172,
85086097,
84380410,
11000525
];

// Id of the first player in BGA Studio
$sid = 2296755;

foreach ($ids as $id) {
// basic tables
self::DbQuery("UPDATE player SET player_id=$sid WHERE player_id = $id" );
self::DbQuery("UPDATE global SET global_value=$sid WHERE global_value = $id" );
self::DbQuery("UPDATE stats SET stats_player_id=$sid WHERE stats_player_id = $id" );

// 'other' game specific tables. example:
// tables specific to your schema that use player_ids
self::DbQuery("UPDATE card SET card_location_arg=$sid WHERE card_location_arg = $id" );

++$sid;
}
}
</pre>

3D

2017-07-09T20:19:18Z

Galehar: Fix formatting

= Overview =

Board Game Arena is using CSS 3D features to provide a basic 3D view of the games.

This is not a "100% real" 3D as this is very difficult to play with real 3D model with CSS, but most of the time it provides a satisfying 3D view of the game.

The objective of 3D is to provide a nice view of the game : 90% of the time, 2D is more suitable for playing. So we don't force developers to make sure games can be played in 3D : this is just a "bonus".

= Enabling 3D =

3D is enabled by default for your game.

You can click on the "3D" button at the top right and see your game in 3D.

If you don't want to allow players to use 3D with your game, you can add this to you "gameinfos.inc.php" file :

'enable_3d' => false,

= Detecting 3D =

When 3D is "on", BGA adds CSS class "mode_3d" to the body element.

In CSS, you should prefix all your 3D mode specific directives by ".mode_3d".

.mode_3d .board {
overflow: visible;
}

In Javascript, you can detect 3D by using the following :

if( this.control3dmode3d )
{
// Only executed in 3d mode
}

= Built-in 3D enhancements =

BGA is doing some built-in 3D enhancements with your 3D adaptations, so your adaptation will have some 3D effects without any efforts :

* When executing a slideToObject, a slideToObjectPos or a slideTemporaryObject, BGA is moving the objects vertically (up, then down).
* It also happens when moving elements of a Stock module, or to a Zone module.

= Enhance your adaptation for 3D =

== Use Z axis ==

Using CSS transform: translateZ, you can translate your HTML elements along the Z axis. Example :

.floating_element {
transform: translateZ( 20px ); /* This element is going to float 20px above the surface */
}

The framework will add the following to all your divs:
transform-style: preserve-3d;

So they will keep their position in 3D space relative to other elemens with the transformation defined. Note that some CSS artifacts can break the css inheritance of the "preserve-3d" like "overflow:auto"

At any moment, you can know the Z position of an element from javascript using :

this.getComputedTranslateZ( html_element );

== Use pre-build BGA 3D CSS classes ==

By adding the following classes to your objects, they will look nicer in 3D:

* thickness: add a (3px) black thickness to your HTML element.

* roundthickness: (to be used with thickness) if your element is a circle, you should add roundthickness so your element thickness can be a circle too.

* whitethickness: (to be used with thickness) if you prefer to have a whitethickness instead of black.

* floatingabove: make your element "float" 10px above the surface, with a nice shadow.

* roundfloatingabove: (to be used with floatingabove) if your element is a circle, use roundfloatingabove in addition to floatingabove.

Note: if you found some generic CSS that may help some other developers for 3D enhancements, please send it to us so we can add it there.

== Setting the default point of view and enabling 3d by default ==

Your game may require to use 3D mode enabled by default and also with a certain custom default PoinOfView. You can achieve this setting in your constructor section of your game:

if (!dojo.hasClass("ebd-body", "mode_3d")) {
dojo.addClass("ebd-body", "mode_3d");
dojo.addClass("ebd-body", "enableTransitions");
$("globalaction_3d").innerHTML = "2D"; // controls the upper right button
this.control3dxaxis = 30; // rotation in degrees of x axis (it has a limit of 0 to 80 degrees in the frameword so users cannot turn it upsidedown)
this.control3dzaxis = 0; // rotation in degrees of z axis
this.control3dxpos = 100; // center of screen in pixels
this.control3dypos = 300; // center of screen in pixels
this.control3dscale = 1.4; // zoom level, 1 is default 2 is double normal size,
this.control3dmode3d = true ; // is the 3d enabled
$("game_play_area").style.transform = "rotatex(" + this.control3dxaxis + "deg) translate(" + this.control3dypos + "px," + this.control3dxpos + "px) rotateZ(" + this.control3dzaxis + "deg) scale3d(" + this.control3dscale + "," + this.control3dscale + "," + this.control3dscale + ")";
}