Pre-release checklist

2017-01-12T02:40:41Z

Victoria la:

Pre-release checklist

2017-01-12T02:36:38Z

Victoria la:

Pre-release checklist

2017-01-12T02:35:30Z

Victoria la:

Studio

2017-01-12T02:15:27Z

Victoria la: /* BGA Developer team organization */

[[File:Bga_studio_small.jpg]]

Note: Please DO NOT translate Studio Documentation, so that there can be one place where you can find the latest information available.

== What is Board Game Arena Studio? ==

'''Board Game Arena Studio''' is a platform to build online board game adaptation using the Board Game Arena platform.

It is open to any gamer with development skills :)

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

(original announcement on BGA forum: http://forum.boardgamearena.com/viewtopic.php?f=10&t=1973)

== Discover BGA Studio in 5 presentations ==

Why, how, what... to start discovering BGA Studio, we prepared 5 "powerpoint" presentations for you:

* [http://www.slideshare.net/boardgamearena/5-reasons-why-you-should-use-bga-studio-for-your-online-board-game 5 reasons why you should use BGA Studio for your online board game]
* [http://www.slideshare.net/boardgamearena/the-8-steps-to-create-a-board-game-on-board-game-arena The 8 steps to create a board game on Board Game Arena]
* [http://www.slideshare.net/boardgamearena/the-bga-framework-at-a-glance The BGA Framework at a glance]
* [http://www.slideshare.net/boardgamearena/bga-studio-focus-on-bga-game-state-machine Focus on BGA game state machine]
* [http://www.slideshare.net/boardgamearena/bga-studio-guidelines BGA developers guidelines]

== How to join the BGA developer team? ==

Please see this page: [[How to join BGA developer team?]]

== Great, I'm in! ... How should I start? ==

If you didn't already, check the presentations at the top of this page to get the basics.

Then, you should checkout the [[First steps with BGA Studio]] to make sure that runs fine.

After that, we advise you to take a peek at one or both of these two game creation tutorials:
* [[Tutorial reversi]]
* [[Tutorial gomoku]]

Then start editing files and see what happens! ;)

If you have any questions, please check out the '''[[Studio FAQ]]''' first, then if you didn't find the answer you were looking for, please post your question on the [http://forum.boardgamearena.com/viewforum.php?f=12 '''development forum'''].

== BGA Studio documentation ==

=== BGA Studio Framework reference ===

This part of the documentation focuses on the development framework itself: functions and methods available to build your game.

[[Studio file reference|File structure of a BGA game]]

==== Game logic ====

* [[Main game logic: yourgamename.game.php]]
* [[Your game state machine: states.inc.php]]
* [[Game database model: dbmodel.sql]]
* [[Players actions: yourgamename.action.php]]
* [[Game material description: material.inc.php]]
* [[Game statistics: stats.inc.php]]

==== Game interface ====

* [[Game interface logic: yourgamename.js]]
* [[Game art: img directory]]
* [[Game interface stylesheet: yourgamename.css]]
* [[Game layout: view and template: yourgamename.view.php and yourgamename_yourgamename.tpl]]
* [[Your game mobile version]]

==== Other components ====

* [[Translations]] (how to make your game translatable)
* [[Game options and preferences: gameoptions.inc.php]]
* [[Game meta-information: gameinfos.inc.php]]
* [[Game replay]]

=== BGA Studio game components reference ===

Game components are useful tools you can use in your game adaptations.

* [[Deck]]: a PHP component to manage cards (deck, hands, picking cards, moving cards, shuffle deck, ...).
* [[Counter]]: a JS component to manage a counter that can increase/decrease (ex: player's score).
* [[Draggable]]: a JS component to manage drag'n'drop actions.
* [[ExpandableSection]]: a JS component to manage a rectangular block of HTML than can be displayed/hidden.
* [[Scrollmap]]: a JS component to manage a scrollable game area (useful when the game area can be infinite. Examples: Saboteur or Takenoko games).
* [[Stock]]: a JS component to manage and display a set of game elements displayed at a position.
* [[Wrapper]]: a JS component to wrap a <div> element around his child, even if these elements are absolute positioned.
* [[Zone]]: a JS component to manage a zone of the board where several game elements can come and leave, but should be well displayed together (See for example: token's places at Can't Stop).

=== BGA Studio user guide ===

This part of the documentation is a user guide for the BGA Studio online development environment.

* [[Tools and tips of BGA Studio]]

* [[Practical debugging]]

* [[Studio logs]]

* [[Studio FAQ]]

* [[Troubleshooting]]

== BGA Developer team organization ==

* [[Steps to create a BGA game]]
* [[Pre-release checklist]]
* [[Post-release phase]]

== Other resources ==

[http://forum.boardgamearena.com/viewforum.php?f=12 Development forum]

[http://forum.boardgamearena.com/viewforum.php?f=4 Bugs forum]

Pre-release checklist

2017-01-12T02:15:24Z

Victoria la: Created page with "If you think your game is ready to be reviewed by by BGA admins and/or Publisher please consult this checklist first * gameinfos.inc.php has correct and up to date information..."

If you think your game is ready to be reviewed by by BGA admins and/or Publisher please consult this checklist first
* gameinfos.inc.php has correct and up to date information about the game
* game box graphics is 3D box version and publisher icon is updated
* tbd

Game interface logic: yourgamename.js

2017-01-03T15:44:41Z

Victoria la: /* Moving elements */

This is the main file for your game interface. Here you will define:

* which actions on the page will generate calls to the server
* what happens when you get a notification for change from the server and how it will show in the browser.

== File structure ==

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

Basically, here's this structure:
* constructor: here you can define variable global to your whole interface.
* setup: this method is called when the page is refreshed, in order you can setup the game interface.
* onEnteringState: the method is called when entering in a new game state. This way you can customize the view for this game state.
* onLeavingState: the method is called when leaving a game state.
* onUpdateActionButtons: called when entering in a new state, in order you can add action buttons in status bar.
* (utility methods): at this place you can define your utility methods
* (player's actions): at this place you can write your handlers for player's action on the interface (ex: click on an item).
* setupNotifications: in this method you associate notifications with notification handlers. This way, for each game notification, you trigger a javascript method to handle it and update the game interface.
* (notification handlers): at this place you can define your notifications handlers.

== General tips ==

; this.player_id
: Id of the player on whose browser the code is running.

; this.isSpectator
: Flag set to true if the user at the table is a spectator (not a player).
: Note: if you want to hide some element for spectators, you'd better use [[Game_interface_stylesheet:_yourgamename.css#spectatorMode|CSS 'spectatorMode' class]].

; this.gamedatas
: Contains your initial set of datas to init the game, created at game start or game refresh (F5)
: You can update it as needed to keep an up to date reference of the game on the client side if you need it (most of the time you don't).

; this.isCurrentPlayerActive()
: Returns true if the player on whose browser the code is running is currently active (it's his turn to play)

; this.getActivePlayerId()
: Return the ID of active player, or null if we are not in a "activeplayer" type state.

; this.getActivePlayers()
: Return an array with the IDs of players that are currently active (or an empty array if there is not).

== Dojo framework ==

BGA is using the [http://dojotoolkit.org/ Dojo Javascript framework].

The Dojo framework allows us to do complex things easier, and the BGA framework is using Dojo framework a lot.

To realize game although, you only need to use a few part of the Dojo framework. All the Dojo methods you need to use are describe on this page.

== Access and manipulate the DOM ==

'''$('some_html_element_id')'''

The $() function is used to get some HTML element using its "id" attribute.

Example 1: modify the content of a "span" element:
<pre>
In your HTML code:
<span id="a_value_in_the_game_interface">1234</span>

In your Javascript code:
$('a_value_in_the_game_interface').innerHTML = "9999";
</pre>

Note: $() is the standard method to access some HTML element with BGA Framework. You must not use "getElementById" function.

'''dojo.style'''

With dojo.style you can modify a CSS property of any HTML element of your interface.

Examples:
<pre>
// Make an element disappear
dojo.style( 'my_element', 'display', 'none' );

// Give an element a 2px border
dojo.style( 'my_element', 'borderWidth', '2px' );

// Change the background position of an element
// (very practical when you are using CSS sprite to transform an element to another)
dojo.style( 'my_element', 'backgroundPosition', '-20px -50px' );
</pre>

Note: you must always use dojo.style to modify CSS properties of HTML elements.

Note²: if you have to modify several CSS properties of an element, or if you have some complex CSS transformation to do, you should consider using dojo.addClass/dojo.removeClass (see below).

'''dojo CSS classes manipulation'''

In many situation, a bunch of many small CSS property update can be replaced by a CSS class change (ie: you add a CSS class to your element instead of applying all modification manually).

Advantages are:
* All your CSS stuff remains in your CSS file.
* You can add/remove a list of CSS modifications with a simple function and whithout error.
* You can test if you applied the stuff to an element with "dojo.hasClass" method.

Example from "Reversi":
<pre>
// We add "possibleMove" to an element
dojo.addClass( 'square_'+x+'_'+y, 'possibleMove' );

// In our CSS file, the class is defined as:
.possibleMove {
background-color: white;
opacity: 0.2;
filter:alpha(opacity=20); /* For IE8 and earlier */
cursor: pointer;
}

// So we've applied 4 CSS property change in one line of code.

// ... and when we need to check if a square is a possible move on client side:
if( dojo.hasClass( 'square_'+x+'_'+y, 'possibleMove' ) )
{ ... }

// ... and if we want to remove all possible moves in one line of code (see "dojo.query" method):
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );
</pre>

Conclusion: we encourage you to use dojo.addClass, dojo.removeClass and dojo.hasClass to make your life easier :)

'''dojo.query'''

With dojo.query, you can query a bunch of HTML elements with a single function, with a "CSS selector" style.

Example:
<pre>
// All elements with class "possibleMove":
var elements = dojo.query( '.possibleMove' );

// Count number of tokens (ie: elements with class "token") on the board (ie: element with id "board"):
dojo.query( '#board .token' ).length;
</pre>

But what is really cool with dojo.query is that you can combine it with almost all methods above.

Examples:
<pre>
// Trigger a method when the mouse enter in any element with class "meeple":
dojo.query( '.meeple' ).connect( 'onmouseenter', this, 'myMethodToTrigger' );

// Hide all meeples who are on the board
dojo.query( '#board .meeple' ).style( 'display', 'none' );
</pre>

'''dojo.place'''

dojo.place is the best function to insert some HTML code somewhere in your game interface without breaking something. It is much better to use that "innerHTML=''" method as soon as you must insert HTML tags and not only values.

<pre>
// Insert your HTML code as a child of a container element
dojo.place( "<your html code>", "your_container_element_id" );

// Replace the container element with your new html
dojo.place( "<your html code>", "your_container_element_id", "replace" );

</pre>

The third parameter of dojo.place can take various interesting value.

values possibles :

"replace" : (see description above).

"first" : Places the node as a child of the reference node. The node is placed as the first child.

"last" : Places the node as a child of the reference node. The node is placed as the last child.

"before" : places the node right before the reference node.

"last (value by default) " : places the node right after the reference node.

"only" : replaces all children of the reference node with the node.

positif integer : This parameter can be a positif integer. In this case, the node will be placed as a child of the reference node with this number (counting from 0). If the number is more than number of children, the node will be appended to the reference node making it the last child.

See also full doc on dojo.place : [http://dojotoolkit.org/reference-guide/1.7/dojo/place.]

Usually, when you want to insert some piece of HTML in your game interface, you should use "[[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl#Javascript_templates|Javascript templates]]".

'''addStyleToClass: function( cssClassName, cssProperty, propertyValue )'''

Same as dojo.style(), but for all the nodes set with the specified cssClassName

=== Animations ===

'''Dojo Animations'''

BGA animations is based on Dojo Animation ([http://dojotoolkit.org/documentation/tutorials/1.8/animation/ see tutorial here]).

However, most of the time, you can just use methods below, which are built on top of Dojo Animation.

Note: one interesting method from Dojo that could be useful from time to time is "Dojo.Animation". It allows you to make any CSS property "slide" from one value to another.

'''this.slideToObject( mobile_obj, target_obj, duration, delay )'''

You can use slideToObject to "slide" an element to a target position.

Sliding element on the game area is the recommended and the most used way to animate your game interface. Using slides allow players to figure out what is happening on the game, as if they were playing with the real boardgame.

The parameters are:
* mobile_obj: the ID of the object to move. This object must be "relative" or "absolute" positioned.
* target_obj: the ID of the target object. This object must be "relative" or "absolute" positioned. Note that it is not mandatory that mobile_obj and target_obj have the same size. If their size are different, the system slides the center of mobile_obj to the center of target_obj.
* duration: (optional) defines the duration in millisecond of the slide. The default is 500 milliseconds.
* delay: (optional). If you defines a delay, the slide will start only after this delay. This is particularly useful when you want to slide several object from the same position to the same position: you can give a 0ms delay to the first object, a 100ms delay to the second one, a 200ms delay to the third one, ... this way they won't be superposed during the slide.

BE CAREFUL: The method returns an dojo.fx animation, so you can combine it with other animation if you want to. It means that you have to call the "play()" method, otherwise the animation WON'T START.

Example:
<pre>
this.slideToObject( "some_token", "some_place_on_board" ).play();
</pre>

'''this.slideToObjectPos( mobile_obj, target_obj, target_x, target_y, duration, delay )'''

This method does exactly the same as "slideToObject", except than you can specify some (x,y) coordinates. This way, "mobile_obj" will slide to the specified x,y position relatively to "target_obj".

Example: slide a token to some place on the board, 10 pixels to the bottom:
<pre>
this.slideToObjectPos( "some_token", "some_place_on_board", 0, 10 ).play();
</pre>

'''this.slideTemporaryObject( mobile_obj_html, mobile_obj_parent, from, to, duration, delay )'''

This method is useful when you want to slide a temporary HTML object from one place to another. As this object does not exists before the animation and won't remain after, it could be complex to create this object (with dojo.place), to place it at its origin (with placeOnObject) to slide it (with slideToObject) and to make it disappear at the end.

slideTemporaryObject does all of this for you:
* mobile_obj_html is a piece of HTML code that represent the object to slide.
* mobile_obj_parent is the ID of an HTML element of your interface that will be the parent of this temporary HTML object.
* from is the ID of the origin of the slide.
* to is the ID of the target of the slide.
* duration/delay works exactly like in "slideToObject"

Example:
<pre>
this.slideTemporaryObject( '<div class="token_icon"></div>', 'tokens', 'my_origin_div', 'my_target_div' );
</pre>

'''this.slideToObjectAndDestroy: function( node, to, time, delay )'''

This method is a handy shortcut to slide an existing HTML object to some place then destroy it upon arrival. It can be used for example to move a victory token or a card from the board to the player panel to show that the player earns it, then destroy it when we don't need to keep it visible on the player panel.

It works the same as this.slideToObject and takes the same arguments.

Example:
<pre>
this.slideToObjectAndDestroy( "some_token", "some_place_on_board", 1000, 0 );
</pre>

'''this.fadeOutAndDestroy( node )'''

This function fade out the target HTML node, then destroy it.

Example:
<pre>
this.fadeOutAndDestroy( "a_card_that_must_disappear" );
</pre>

CAREFUL: the HTML node still exists until during few milliseconds, until the fadeOut has been completed.

'''Rotating elements'''

You can check here [http://jimfulton.info/demos/dojo-animated-rotate.html an example of use] of Dojo to make an element rotate.

This example combines "Dojo.Animation" method and a CSS3 property that allow you to rotate the element.

IMPORTANT: to asses browser compatibility, you must select the CSS property to use just like in the example (see sourcecode below):

<pre>
var transform;
dojo.forEach(
['transform', 'WebkitTransform', 'msTransform',
'MozTransform', 'OTransform'],
function (name) {
if (typeof dojo.body().style[name] != 'undefined') {
transform = name;
}
});
// ... and then use "transform" as the name of your CSS property for rotation
</pre>

=== Moving elements ===

'''this.placeOnObject( mobile_obj, target_obj )'''

placeOnObject works exactly like "slideToObject", except that the effect is immediate.

This is not really an animation, but placeOnObject is frequently used before starting an animation.

Example:
<pre>
// (We just created an object "my_new_token")

// Place the new token on current player board
this.placeOnObject( "my_new_token", "overall_player_board_"+this.player_id );

// Then slide it to its position on the board
this.slideToObject( "my_new_token", "a_place_on_board" ).play();
</pre>

'''this.placeOnObjectPos( mobile_obj, target_obj, target_x, target_y )'''

This method works exactly like placeOnObject, except than you can specify some (x,y) coordinates. This way, "mobile_obj" will be placed to the specified x,y position relatively to "target_obj".

'''this.attachToNewParent( mobile_obj, target_obj )'''

With this method, you change the HTML parent of "mobile_obj" element. "target_obj" is the new parent of this element. The beauty of
attachToNewParent is that the mobile_obj element DOES NOT MOVE during this process.

Note: what happens is that the method calculate a relative position of mobile_obj to make sure it does not move after the HTML parent changes.

Why using this method?

Changing the HTML parent of an element can be useful for the following reasons:
* When the HTML parent moves, all its child are moving with them. If some game elements is no more linked with a parent HTML object, you may want to attach it to another place.
* The z_order (vertical order of display) depends on the position in the DOM, so you may need to change the parent of some game elements when they are moving in your game area.

CAREFUL: this function destroys original object and places a clone onto a new parent, this will break all references to this HTML element (ex: dojo.connect).

== Players input ==

'''dojo.connect'''

Used to associate a player event with one of your notification method.

Example: associate a click on an element ("my_element") with one of our method ("onClickOnMyElement"):
<pre>
dojo.connect( $('my_element'), 'onclick', this, 'onClickOnMyElement' );
</pre>

Note: this is the only possible correct way to associate a player input event to your code, and you must not use anything else.

'''this.checkAction( "my_action_name" )'''

Usage: checkAction: function( action, nomessage )

Check if player can do the specified action by taking into account:
* current game state
* interface locking (a player can't do any action if an action is already in progress)

return true if action is authorized (ie: the action is listed as a "possibleaction" in current game state).

return false and display an error message if not (display no message if nomessage parameter is true). The displayed error message could be either "This move is not allowed at this moment" or "An action is already in progress".

Example:
<pre>
function onClickOnGameElement( evt )
{
if( this.checkAction( "my_action" ) )
{
// Do the action
}
}
</pre>

'''this.ajaxcall( url, parameters, obj_callback, callback, callback_error )'''

This method must be used to send a player input to the game server.

* url: the url of the action to perform. For a game, it must be: "/<mygame>/<mygame>/myAction.html"
* parameters: an array of parameter to send to the game server. Note that "lock:true" must always be specified in this list of parameter in order the interface can be locked during the server call.
* obj_callback: must be set to "this".
* callback: a function to trigger when the server returns and everything went fine.
* callback_error: (optional and rarely used) a function to trigger when the server returns an error.

Usage:
<pre>
this.ajaxcall( '/mygame/mygame/myaction.html', { lock: true,
arg1: myarg1,
arg2: myarg2,
...
}, this, function( result ) {
// Do some stuff after a successful call
} );
</pre>

Restricted arguments names (please don't use them):
* "action"
* "module"
* "class"

'''this.confirmationDialog()'''

Display a confirmation dialog with a yes/no choice.

We advice you to NOT use this function unless the player action is really critical and could ruins the game, because it slows down the game and upset players.

Usage: this.confirmationDialog( "Question to displayed", callback_function_if_click_on_yes );

Example:
<pre>
this.confirmationDialog( _('Are you sure to use this bonus (points penalty at the end of the game) ?'),
dojo.hitch( this, function() {
this.ajaxcall( '/seasons/seasons/useBonus.html',
{ id:bonus_id, lock:true }, this, function( result ) {} );
} ) );
</pre>

; addEventToClass: function( cssClassName, eventName, functionName )
: Same as dojo.connect(), but for all the nodes set with the specified cssClassName

'''this.addActionButton( id, label, method, (opt)depreciated, (opt)bHighlight, (opt)color )'''

You can use this method to add an action button in the main action status bar.

Arguments:
* id: a ID that should be unique in your HTML DOM document.
* label: the text of the button. Should be translatable (use _() function).
* method: the name of your method that must be triggered when the player clicks on this button.
* depreciated (optional): do not use this. Please not specify this argument or use "null".
* bHighlight (optional): if set to "true", the button is going blink to catch player's attention. Please don't abuse of blinking button.
* color: could be '''blue''' (default), '''red''' or '''gray'''.

You should only use this method in your "onUpdateActionButtons" method. Usually, you use it like this (from Hears example):

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

if( this.isCurrentPlayerActive() )
{
switch( stateName )
{
case 'giveCards':
this.addActionButton( 'giveCards_button', _('Give selected cards'), 'onGiveCards' );
break;

}
}
},
</pre>

In the example above, we are adding a "Give selected cards" button in the case we are on game state "giveCards". When player clicks on this button, it triggers our "onGiveCards" method.

== Translations ==

See [[Translations]]

== Notifications ==

When something happens on the server side, your game interface Javascript logic received a notification.

Here's how you can handle these notifications on the client side.

=== Subscribe to notifications ===

Your Javascript "setupNotifications" method is the place where you can subscribe to notifications from your PHP code.

Here's how you associate one of your Javascript method to a notification "playDisc" (from Reversi example):

<pre>
// In setupNotifications method:
dojo.subscribe( 'playDisc', this, "notif_playDisc" );
</pre>

Note: the "playDisc" corresponds to the name of the notification you define it in your PHP code, in your "notifyAllPlayers" or "notifyPlayer" method.

Then, you have to define your "notif_playDisc" method:

<pre>
notif_playDisc: function( notif )
{
// Remove current possible moves (makes the board more clear)
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );

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

In a notification handler like our "notif_playDisc" method, you can access to all notifications arguments with "notif.args".

Example:
<pre>
// If you did this on PHP side:
self::notifyAllPlayers( "myNotification", '', array( "myArgument" => 3 ) );

// On Javascript side, you can access the "myArgument" like this:
notif_myNotification: function( notif )
{
alert( "myArgument = " + notif.args.myArgument );
}
</pre>

=== Synchronous notifications ===

When several notifications are received by your game interface, these notifications are processed immediately, one after the other, in the same exact order they have been generated in your PHP game logic.

However, sometimes, you need to give some time to the players to figure out what happened on the game before jumping to the next notification. Indeed, in many games, they are a lot of automatic actions, and the computer is going to resolve all these actions very fast if you don't tell it not to do so.

As an example, for Reversi, when someone is playing a disc, we want to wait 500 milliseconds before doing anything else in order the opponent player can figure out what move has been played.

Here's how we do this, right after our subscription:
<pre>
dojo.subscribe( 'playDisc', this, "notif_playDisc" );
this.notifqueue.setSynchronous( 'playDisc', 500 ); // Wait 500 milliseconds after executing the playDisc handler
</pre>

=== Pre-defined notification types ===

'''tableWindow''' - This defines notification to display [[Game_interface_logic:_yourgamename.js#Scoring_dialogs|Scoring Dialogs]], see below.

'''message''' - This defines notification that shows on players log and have no other effect

// You can call this on php side without doing anything on client side
self::notifyAllPlayers( 'message', 'hello', array( ) );

== Tooltips ==

'''this.addTooltip( nodeId, _( helpString ), _( actionString ), delay )'''

Add a simple text tooltip to the DOM node.

Specify 'helpString' to display some information about "what is this game element?".
Specify 'actionString' to display some information about "what happens when I click on this element?".

You must specify both helpString and actionString. Most of the time, you use only one and specify a void string ("") for the other one.

Usually, _() must be used for the text to be marked for translation.

"Delay" is an optional parameter. Usually, it is primarily used to specify a zero delay for some game element when the tooltip gives really important information for the game - but remember: no essential information must be placed in tooltips as they won't be displayed in some browser (see Guidelines).

Example:
<pre>
this.addTooltip( 'cardcount', _('Number of cards in hand'), '' );
</pre>

'''this.addTooltipHtml( nodeId, html, delay )'''

Add an HTML tooltip to the DOM node (for more elaborate content such as presenting a bigger version of a card).

'''this.addTooltipToClass( cssClass, _( helpString ), _( actionString ), delay )'''

Add a simple text tooltip to all the DOM nodes set with this cssClass.

IMPORTANT: all concerned nodes must have IDs to get tooltips.

'''this.addTooltipHtmlToClass( cssClass, html, delay )'''

Add an HTML tooltip to to all the DOM nodes set with this cssClass (for more elaborate content such as presenting a bigger version of a card).

IMPORTANT: all concerned nodes must have IDs to get tooltips

'''this.removeTooltip( nodeId )'''

Remove a tooltip from the DOM node.

== Dialogs, warning messages, confirmation dialogs, ... ==

=== Warning messages ===

Sometimes, there is something important that is happening on the game and you have to make sure all players get the message. Most of the time, the evolution of the game situation or the game log is enough, but sometimes you need something more visible.

Ex: someone fulfill one of the end of the game condition, so this is the last turn.

'''this.showMessage( msg, type )'''

showMessage shows a message in a big rectangular area on the top of the screen of current player.

* "msg" is the string to display. It should be translated.
* "type" can be set to "info" or "error". If set to "info", the message will be an informative message on a white background. If set to "error", the message will be an error message on a red background.

Important: the normal way to inform players about the progression of the game is the game log. "showMessage" is intrusive and should not be used often.

=== Confirmation dialog ===

When an important action with a lot of consequences is triggered by the player, you may want to propose a confirmation dialog.

CAREFUL: the general guidelines of BGA is to AVOID the use of confirmation dialog. Confirmation dialogs slow down the game and bother players. The players knows that they have to pay attention about each move when they are playing online.

The situation where you should use a confirmation dialog are the following:
* It must not happen very often during a game.
* It must be linked to an action that can really "kill a game" if the player do not pay attention.
* It must be something that can be done by mistake (ex: a link on the action status bar).

How to display a confirmation dialog:
<pre>
this.confirmationDialog( _('Are you sure you want to make this?'), dojo.hitch( this, function() {
this.ajaxcall( '/mygame/mygame/makeThis.html', { lock:true }, this, function( result ) {} );
} ) );
</pre>

=== Multiple choice dialog ===
You can use this dialog to give user a choice with small amount of options:
<pre>
var keys = [1,5,10];
this.multipleChoiceDialog(
_('How many bugs to fix?"), keys,
dojo.hitch(this, function(choice) {
var bugchoice = keys[choice];
console.log('dialog callback with '+bugchoice);
this.ajaxcall( '/mygame/mygame/fixBugs.html', { bugs: bugchoice}, this, function( result ) {} ); }));
</pre>

=== Dialogs ===

At first, you shouldn't use dialogs windows.

BGA guidelines specify that all game elements should be displayed on the main screen. Players can eventually scroll down to see game elements they don't need to see anytime, and you may eventually create anchors to move between game area section. Of course dialogs windows are very practical, but the thing is: all players know how to scroll down, and not all players know how to show up your dialog window. In addition, when the dialog shows up, players can't access the other game components.

Sometimes although, you need to display a dialog window. Here is how you do this:

// Create the new dialog. You should store the handler in a member variable to access it later
this.myDlg = new dijit.Dialog({ title: _("my dialog title to translate") });

// Create the HTML of my dialog.
// The best practice here is to use [[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl#Javascript_templates|Javascript templates]]
var html = this.format_block( 'jstpl_myDialogTemplate', {
arg1: myArg1,
arg2: myArg2,
...
} );

// Show the dialog
this.myDlg.attr("content", html );
this.myDlg.show();

// Now that the dialog has been displayed, you can connect your method to some dialog elements
// Example, a "close" button:
dojo.connect( $('closeDlg'), 'onclick', this, function(evt){
evt.preventDefault();
this.myDlg.hide();
} );

Tip: be careful with "hide()" method to close your dialog: the dialog and its content is not completely removed from the DOM. It can cause you problems if you try to display the same dialog several times. A good practice is to wrap all the content of your dialog in a <nowiki><div id='myDlgContent'></nowiki> div element, and to call "dojo.destroy('myDlgContent')" before displaying your dialog.

=== Scoring dialogs ===

Sometimes at the end of a round you want to display a big table that details the points wins in each section of the game.

Example: in Hearts game, we display at the end of each round the number of "heart" cards collected by each player, the player who collected the Queen of Spades, and the total number of points loose by each player.

Scoring dialogs are managed entirely on '''PHP side''', but they are described here as their effects are visible only on client side.

Displaying a scoring dialog is quite simple and is using a special notification type: "tableWindow":
<pre>
// on PHP side:
$this->notifyAllPlayers( "tableWindow", '', array(
"id" => 'finalScoring',
"title" => clienttranslate("Title of the scoring dialog"),
"table" => $table
) );
</pre>

The "table" argument is a 2 dimensional PHP array that describe the table you want to display, line by line and column by column.

Example: display an 3x3 array of strings
<pre>
$table = array(
array( "one", "two", "three" ), // This is my first line
array( "four", "five", "six" ), // This is my second line
array( "seven", "height", "nine" ) // This is my third line
);
</pre>

As you can see above, in each "cell" of your array you can display a simple string value. But you can also display a complex value with a template and associated arguments like this:
<pre>
$table = array(
array( "one", "two", array( "str" => "a string with an ${argument}", "args" => array( 'argument' => 'argument_value' ) ) ),
array( "four", "five", "six" ),
array( "seven", "height", "nine" )
);
</pre>

This is especially useful when you want to display player names with colors. Example from "Hearts":
<pre>
$firstRow = array( '' );
foreach( $players as $player_id => $player )
{
$firstRow[] = array( 'str' => '${player_name}',
'args' => array( 'player_name' => $player['player_name'] ),
'type' => 'header'
);
}
$table[] = $firstRow;
</pre>

You can also use three extra attributes in the parameter array for the notification:

<pre>
$this->notifyAllPlayers( "tableWindow", '', array(
"id" => 'finalScoring',
"title" => clienttranslate("Title of the scoring dialog"),
"table" => $table,
"header" => array('str' => clienttranslate('Table header with parameter ${number}'),
'args' => array( 'number' => 3 ),
),
"footer" => '<div>Some footer</div>',
"closing" => clienttranslate( "Closing button label" )
) );
</pre>

*'''header''': the content for this parameter will display before the table (also, the html will be parsed and player names will be colored according to the current game colors).
*'''footer''': the content for this parameter will display after the table (no parsing for coloring the player names)
*'''closing''': if this parameter is used, a button will be displayed with this label at the bottom of the popup and will allow players to close it (more easily than by clicking the top right 'cross' icon).

== Update players score ==

Increase a player score (with a positive or negative number):

<pre>
this.scoreCtrl[ player_id ].incValue( score_delta );
</pre>

Set a player score to a specific value:

<pre>
this.scoreCtrl[ player_id ].setValue( new_score );
</pre>

== Players panels ==

=== Adding stuff to player's panel ===

At first, create a new "JS template" string in your template (tpl) file:

(from Gomoku example)
<pre>
var jstpl_player_board = '\<div class="cp_board">\
<div id="stoneicon_p${id}" class="gmk_stoneicon gmk_stoneicon_${color}"></div><span id="stonecount_p${id}">0</span>\
</div>';
</pre>

Then, you add this piece of code in your JS file to add this template to each player panel:

<pre>
// Setting up player boards
for( var player_id in gamedatas.players )
{
var player = gamedatas.players[player_id];

// Setting up players boards if needed
var player_board_div = $('player_board_'+player_id);
dojo.place( this.format_block('jstpl_player_board', player ), player_board_div );
}
</pre>

(Note: the code above is of course from your "setup" function in your Javascript).

Very often, you have to distinguish current player and others players. In this case, you just have to create another JS template (ex: jstpl_otherplayer_board) and use it when "player_id" is different than "this.player_id".

=== Player's panel disabling/enabling ===

'''this.disablePlayerPanel( player_id )'''

Disable given player panel (the panel background become gray).

Usually, this is used to signal that this played passes, or will be inactive during a while.

Note that the only effect of this is visual. There are no consequences on the behaviour of the panel itself.

'''this.enablePlayerPanel( player_id )'''

Enable a player panel that has been disabled before.

'''this.enableAllPlayerPanels()'''

Enable all player panels that has been disabled before.

== Image loading ==

See also [[Game_art:_img_directory]].

'''Be careful''': by default, ALL images of your img directory are loaded on a player's browser when he loads the game. For this reason, don't let in your img directory images that are not useful, otherwise it's going to slowdown the game load.

'''dontPreloadImage( image_file_name )'''

Using dontPreloadImage, you tell the interface to not preload a specific image in your img directory.

Example of use:
<pre>
this.dontPreloadImage( 'cards.png' );
</pre>

This is particularly useful if for example you have 2 different themes for a game. To accelerate the loading of the game, you can specify to not preload images corresponding to the other theme.

Another example of use: in "Gosu" game with Kamakor extension, you play with 5 sets of cards among 10 available. Cards images are organized by sets, and we only preload the images corresponding to the 5 current sets.

'''Note:''' You don't need to specify to not preload game box images (game_box.png, game_box75.png...) since they are not preloaded by default.

== Other useful stuff ==

'''dojo.hitch'''

With dojo.hitch, you can create a callback function that will run with your game object context whatever happen.

Typical example: display a BGA confirmation dialog with a callback function created with dojo.hitch:

<pre>
this.confirmationDialog( _('Are you sure you want to make this?'), dojo.hitch( this, function() {
this.ajaxcall( '/mygame/mygame/makeThis.html', { lock:true }, this, function( result ) {} );
} ) );
</pre>

In the example above, using dojo.hitch, we are sure that the "this" object will be set when the callback is called.

; updateCounters(counters)
: Useful for updating game counters in the player panel (such as resources).
: 'counters' arg is an associative array [counter_name_value => [ 'counter_name' => counter_name_value, 'counter_value' => counter_value_value], ... ]
: All counters must be referenced in this.gamedatas.counters and will be updated.
: DOM objects referenced by 'counter_name' will have their innerHTML updated with 'counter_value'.

== BGA GUI components ==

BGA framework provides some useful ready-to-use components for the game interface:

[[Studio#BGA_Studio_game_components_reference]]

Note that each time you are using an additional component, you must declare it at the top of your Javascript file in the list of modules used.

Example if you are using "ebg.stock":
<pre>
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/stock" /// <=== we are using ebg.stock module
],
</pre>

Troubleshooting

2016-12-24T03:02:10Z

Victoria la: /* Game "spontaneously" transition to a new state without user input */

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

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

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

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

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

=== 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 in php does not mean string concatenation, only in javascript,
+ means integer arithmetics. So change + to . (dot)

Troubleshooting

2016-12-24T02:56:55Z

Victoria la: /* Javascript: do not use substr with negative numbers */

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

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

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

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

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

Troubleshooting

2016-12-24T02:52:33Z

Victoria la: /* Unexpected error: Unexpected final game state (XX) */

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

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

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

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

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

Tools and tips of BGA Studio

2016-11-27T23:21:43Z

Victoria la: /* Version Control */

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

To start a game:
* Create a new table with your game.
* 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 Tools ==
=== 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 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 -deplay 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.

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

=== Debugging ===

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

=== Version Control ===
Studio providers svn for you code on server, however there is no way to access history, restore or do anything
with it unless you ask admins. If you want 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>. Also its unclear if you can put publisher's images there, so I suggest not committing img/ folder.

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

=== ImageMagick ===
Handy set of image manipulation command line tools (Linux), 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:

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

== 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 parent project folder create directory test/ and save your html as test/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/mygame.css"/>

You project structure will look like this

mygame
img/ <-- your images
mygame.css <-- your original css
...
test/
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.

Tools and tips of BGA Studio

2016-11-27T23:21:11Z

Victoria la: /* Version Control */

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

To start a game:
* Create a new table with your game.
* 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 Tools ==
=== 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 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 -deplay 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.

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

=== Debugging ===

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

=== Version Control ===
Studio providers svn for you code on server, however there is no way to access history, restore or do anything
with it unless you ask admins. If you want 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 https://github.com/<yourname>/bga-<yourgame>. Also its unclear if you can put publisher's images there, so I suggest not committing img/ folder.

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

=== ImageMagick ===
Handy set of image manipulation command line tools (Linux), 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:

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

== 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 parent project folder create directory test/ and save your html as test/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/mygame.css"/>

You project structure will look like this

mygame
img/ <-- your images
mygame.css <-- your original css
...
test/
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.

First steps with BGA Studio

2016-11-27T23:18:10Z

Victoria la: /* Commit your changes */

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

== Check projects in progress and available game licences ==

On the left menu, you can check game projects under development and available game licences. From this point, you can choose what you want to do:
* Join an existing project.
* Create a new project.
* Try to get a licence for a game you don't see in the "available game licences" page (see how-to on "available licences" page).

== Create a new game project ==

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

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

== 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 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 our [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 games / Commit my modifications". 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, 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.

For more information on the specificites of each file, please check out the [[Studio#BGA_Studio_documentation | reference documentation for the framework]].

First steps with BGA Studio

2016-11-27T23:15:03Z

Victoria la: /* Let's code! */

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

== Check projects in progress and available game licences ==

On the left menu, you can check game projects under development and available game licences. From this point, you can choose what you want to do:
* Join an existing project.
* Create a new project.
* Try to get a licence for a game you don't see in the "available game licences" page (see how-to on "available licences" page).

== Create a new game project ==

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

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

== 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 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 our [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 games / Commit my modifications". 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.

== That's all! ==

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

For more information on the specificites of each file, please check out the [[Studio#BGA_Studio_documentation | reference documentation for the framework]].

First steps with BGA Studio

2016-11-27T23:12:30Z

Victoria la: /* Connect to your SFTP folder */

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

== Check projects in progress and available game licences ==

On the left menu, you can check game projects under development and available game licences. From this point, you can choose what you want to do:
* Join an existing project.
* Create a new project.
* Try to get a licence for a game you don't see in the "available game licences" page (see how-to on "available licences" page).

== Create a new game project ==

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

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

== 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 launch 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 on the 'Exit game' icon on the top right, and in the popup choose 'Express game 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 our [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 games / Commit my modifications". 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.

== That's all! ==

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

For more information on the specificites of each file, please check out the [[Studio#BGA_Studio_documentation | reference documentation for the framework]].

Tools and tips of BGA Studio

2016-11-23T04:49:02Z

Victoria la: /* Client Tips */

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

To start a game:
* Create a new table with your game.
* 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 Tools ==
=== 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 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 -deplay 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.

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

=== Debugging ===

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

=== Version Control ===
Studio providers svn for you code on server, however there is no way to access history, restore or do anything
with it unless you ask admins. If you want to keep your code in another repository. I suggest to use git with local repo, which you can sync to cloud or backup.

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

=== ImageMagick ===
Handy set of image manipulation command line tools (Linux), 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:

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

== 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 parent project folder create directory test/ and save your html as test/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/mygame.css"/>

You project structure will look like this

mygame
img/ <-- your images
mygame.css <-- your original css
...
test/
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.

Tools and tips of BGA Studio

2016-11-23T04:07:29Z

Victoria la: /* ImageMagick */

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

To start a game:
* Create a new table with your game.
* 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 Tools ==
=== 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 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 -deplay 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.

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

=== Debugging ===

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

=== Version Control ===
Studio providers svn for you code on server, however there is no way to access history, restore or do anything
with it unless you ask admins. If you want to keep your code in another repository. I suggest to use git with local repo, which you can sync to cloud or backup.

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

=== ImageMagick ===
Handy set of image manipulation command line tools (Linux), 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:

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

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

Help

2016-11-13T18:16:25Z

Victoria la: /* Games */

Help

2016-11-13T18:15:29Z

Victoria la: /* Games */

Tools and tips of BGA Studio

2016-10-14T12:35:00Z

Victoria la:

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

To start a game:
* Create a new table with your game.
* 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 Tools ==
=== 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 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 -deplay 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.

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

=== Debugging ===

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

=== Version Control ===
Studio providers svn for you code on server, however there is no way to access history, restore or do anything
with it unless you ask admins. If you want to keep your code in another repository. I suggest to use git with local repo, which you can sync to cloud or backup.

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

=== 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 time is 600x600 PNG file with every time in separate file. You want .jpg instead of .png to make it not like 20Mb, all images in one column with size 128x128
/usr/bin/montage `ls Tiles*.png` -tile 1 -geometry 128x128+0+0 ../out/tiles128.jpg

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

Studio logs

2016-10-14T12:28:13Z

Victoria la: /* BGA unexpected exceptions logs */

BGA Studio logs are available directly from your game development interface.

Logs allows you to check out what happened recently on server and to debug your game.

== BGA request&SQL logs ==

This log is useful:
* When you want to check what SQL requests has been built during a request.
* When you want to debug your PHP code using "self::trace"
* When you want to know why a request takes too many time.

On this log, you can see:

=== Your requests ===

Example:

20/06 21:50:56 [info] [T403] [4/mytest0] /cinco/cinco/exchange4Cards.html?id=4&lock=97d1c7a1-903a-4d1f-8206-de39ce8204fc&table=403&testuser=4&dojo.preventCache=1371757856044

Note that the best way to check your Ajax request is to read the [[http://en.doc.boardgamearena.com/Tools_and_tips_of_BGA_Studio#Input.2FOutput_debugging_section Input/Output section]].

=== Request responses ===

Example:

20/06 21:50:56 [notice] [T403] [4/mytest0] OK-0 169 d141 c8 e0 I9 A158 V0 T0 /cinco/cinco/exchange4Cards.html?id=4&lock=97d1c7a1-903a-4d1f-8206-de39ce8204fc&table=403&testuser=4&dojo.preventCache=1371757856044

You can recognize a response because it contains [notice]. Usually, there is one response for each request.

Let's details the beginning of the log:
* 20/06 21:50:56: the date
* [notice]
* [T403]: this is a log from table 403
* [4/mytest0]: this is use "mytest0", with id 4
* OK-0: it means that the request ended up successfully, with no exception (expected or unexpected).
* 169: this is the time taken to process the request (169ms).
* d141: this is the total Database time used to process the request (141ms).

=== SQL requests ===

Example:
20/06 21:50:56 [info] [T403] [4/mytest0] 0.26 SELECT player_tokenColor FROM player WHERE player_id ='4'

All requests to Database are traced in this log. You can see here the time take by the request (0,26ms).

=== Custom trace ===

You can use special PHP methods in your PHP code to left some trace in this log:
* self::trace( "your message here" ); // Display "your message here" in the log
* self::dump( "My variable", $variable_to_dump ); // Display the content of $variable_to_dump in the log

== BGA unexpected exceptions logs ==

In this log you can check the last Unexpected exceptions from your game.

Exceptions management on PHP side [[http://en.doc.boardgamearena.com/Main_game_logic:_yourgamename.game.php#Managing_errors_and_exceptions is described here]].

The log displayed the complete stacktrace of the exception, so you can debug it.

The SQL log is very verbose and sometimes it too hard to extract your tracing from it, in this case you can use error log for tracing temporarily.
You can add debug statement using self::warn() which will appear in that the log. Do not leave these tracing method calls after you done debugging unless they
are real warnings or errors (only the error log level will appear in production).

Practical debugging

2016-10-14T12:26:51Z

Victoria la: /* Add traces to your code */

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

== Tools ==

To work on BGA Studio, we recommend you to use [www.google.com/chrome Google Chrome] as it's the current fastest browser for BGA platform, and it's available in all OS.

Another reason to use Chrome is that it embed all 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 check 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 developper]

To debug with Internet Explorer, we advise you to use one of the most recent version (ex: IE9). Last versions of Internet Explorer have way 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 don'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]].

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

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 in 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 commited to the database, anyway.
* Then, I use '''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>

=== Add traces to your code ===

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

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

== Debugging my HTML/CSS layout ==

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

A first 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 of its CSS property or because of anything else.

Another tip: sometimes, you change a CSS property with 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 (thre 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 it's HTML code and associated CSS styles.
* You can even modify directly some CSS property and see if how it looks immediately on the game interface.

== Debugging my Javascript game interface logic ==

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

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

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

PHP side is more reliable and simpler to debug than Javascript. Then, when you need to perform a complex operation, check first it you can't write it on server side first.

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

Note: check Reversi example for this.

=== 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 get plainly displayed. But this is sometimes useful just with messages to make sure which way the execution goes.

== Some frequent errors ==

See [[Troubleshooting]].

2016-07-29T01:06:06Z

Victoria la: /* Some frequent errors */

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

== Tools ==

To work on BGA Studio, we recommend you to use [www.google.com/chrome Google Chrome] as it's the current fastest browser for BGA platform, and it's available in all OS.

Another reason to use Chrome is that it embed all 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 check 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 developper]

To debug with Internet Explorer, we advise you to use one of the most recent version (ex: IE9). Last versions of Internet Explorer have way 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 don'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]].

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

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 in 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 commited to the database, anyway.
* Then, I use '''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>

=== Add traces to your code ===

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

'''self::debug( $message );''' // debug level logging

'''self::trace( $message );''' // info level logging

'''self::warn( $message );''' // warning level logging

'''self::error( $message );''' // error level logging

To see the logs, you should check the "Current table error log" in the [[Studio_back-office|Studio backoffice]].

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.

== Debugging my HTML/CSS layout ==

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

A first 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 of its CSS property or because of anything else.

Another tip: sometimes, you change a CSS property with 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 (thre 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 it's HTML code and associated CSS styles.
* You can even modify directly some CSS property and see if how it looks immediately on the game interface.

== Debugging my Javascript game interface logic ==

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

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

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

PHP side is more reliable and simpler to debug than Javascript. Then, when you need to perform a complex operation, check first it you can't write it on server side first.

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

Note: check Reversi example for this.

=== 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 get plainly displayed. But this is sometimes useful just with messages to make sure which way the execution goes.

== Some frequent errors ==

See [[Troubleshooting]].