Board Game Arena - 사용자 기여 [ko]

Contact us

2025-06-30T15:54:55Z

Sourisdudesert:

'''Board Game Arena''' is located in France.

== Contact e-mail ==

contact(at)boardgamearena.com

We receive '''a lot''' of e-mails. Please do not send us an e-mail in any of these two cases:

* If you want to report a bug, please do it in the [http://boardgamearena.com/#!bugs bug reporting system]
* If you want to report a player for violation of BGA policy, use the "report this player" button on his/her profile.

Grade

2014-07-07T16:27:52Z

Sourisdudesert: Undo revision 1083 by Da man (talk)

Board Game Arena is a friendly and respectful community of players. The moderation and grades system help us to ensure that the minority of players who disrespect the spirit of this website can't bother other players.

When you register on Board Game Arena, you're a mortal. You can access most of the functionalities of this website, except some of them (ex: speaking on global chat).

After a while, you are promoted to the angel grade. With this grade you are able to access all functionalities of the service. But, if you go against the Board Game Arena terms, you can be moderated and demoted to devilkin or demon.

If you manage to become a well appreciated player, you can become a moderator with a superior grade: seraph or cherub.

== All grades ==

* '''Mortal''': this is your grade when you registered on Board Game Arena. You can access almost all functionalities of the website (but you can't speak on general channel).

* '''Angel''': this is the grade of regular players. To be promoted to this grade, you need: 3 days seniority, 3 games played and 3 positive reputation points.

* '''Seraph''': this is the moderator grade. Seraphim can punish players who disrespect BGA terms of use: reputation penalties, inferior grade.

* '''Cherub''': this is the super moderator grade. Cherubim check that Seraphim are fair and unbiased.

* '''Archangel''': this is the Board Game Arena administrators' grade.

* '''Devilkin''': due to a terms of use violation, this player is not allowed to speak on Board Game Arena (or publish anything) during a period of time.

* '''Demon''': due to a major terms of use violation, this player is not allowed to do anything on the website during a period of time (or forever ...)

Multipleaccounts

2014-05-12T16:29:11Z

Sourisdudesert:

== The Main Rule ==

'''One BGA account = One person'''

== Playing from the same IP ==

This is '''authorized''' to play at the same table from the same IP (internet address).

The warning message "this player plays from the same internet address than another player" is a '''simple warning'''. It is a useful warning, because the other players have the right to know that there are players at their table that are able to discuss out of game.

If you want to play from the same internet address than another person:
* The best option is not to play at the same table, or play at a table where you know everyone.
* If you play with strangers, make them comfortable by the fact you are 2 (or more) different people: don't discuss about the game outside the chatroom, don't collaborate (or do kingmaking) with your partner, and so on.

When some of your opponents are playing from the same IP:
* You may refuse (politely) to play with them.
* You should probably be vigilant and check that they are not collaborating during the game.
* But you don't have to report them until they are doing a concrete kingmaking action. If you report some players saying that "they are playing from the same IP" without any kingmaking proof, we will close your report.

== Boosting your ELO by playing against yourself ==

This is the most stupid and useless thing to do on BGA.

Why? Because this is very easy to detect, and because the penalty is:
* all your secondary account are removed.
* your primary account is reset to 1500 ELO for all games.

Why this is so easy to detect:
* When you start having a very good ELO, all other good players will look at you and your game history. In the game history, this is really easy to see how you manage to have a good ELO.
* In BGA, every game can be replayed. So if a game is suspect, anyone can replay it and check if this is a real game or a fake game.
* In addition to this, we are using some automatic methods and some technical information that allow us to check if "one person = one account".
* Consequently, it happens that some players manage to do ELO boosting, but at the end they are all detected and reset to 1500. This is why this is a waste of time for everyone, and this is why this is useless.

If you have a lot of time to spend, please try to get better at this game and please do not try to cheat.

Multipleaccounts

2014-05-05T14:07:25Z

Sourisdudesert:

Multipleaccounts

2014-05-05T13:58:40Z

Sourisdudesert:

Multipleaccounts

2014-05-05T13:58:24Z

Sourisdudesert: Created page with "Board Game Arena multiple accounts policy == The Main Rule == '''One BGA account = One person''' == Playing from the same IP == This is '''authorized''' to play at the sam..."

Board Game Arena multiple accounts policy

== The Main Rule ==

'''One BGA account = One person'''

== Playing from the same IP ==

This is '''authorized''' to play at the same table from the same IP (internet address).

The warning message "this player plays from the same internet address than another player" is a '''simple warning'''. It is a useful warning, because the other players have the right to know that there are players at their table that are able to discuss out of game.

If you want to play from the same internet address than another person:
* The best option is not to play at the same table, or play at a table where you know everyone.
* If you play with strangers, make them comfortable by the fact you are 2 (or more) different people: don't discuss about the game outside the chatroom, don't collaborate (or do kingmaking) with your partner, and so on.

When some of your opponents are playing from the same IP:
* You may refuse (politely) to play with them.
* You should probably be vigilant and check that they are not collaborating during the game.
* But you don't have to report them until they are doing a concrete kingmaking action. If you report some players saying that "they are playing from the same IP" without any kingmaking proof, we will close your report.

Game interface logic: yourgamename.js

2014-03-24T17:43:35Z

Sourisdudesert: /* Adding stuff to player's panel */

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

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

Note: the third parameter of dojo.place can take various interesting value: "first", "after", ... [http://dojotoolkit.org/reference-guide/1.7/dojo/place.html See full doc on 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 than "slideToObjectPos", 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: when you attach an HTML element with a new parent, you 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 )'''

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: if set to "true", the button is going blink to catch player's attention. Please don't abuse of blinking button.

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>

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

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

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

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

<pre>

// 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();
} );

</pre>

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 "<div id='myDlgContent'>" 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" => '<div>Some header</div>',
"footer" => '<div>Some footer</div>',
"closelabel" => 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)
*'''closelabel''': 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). NB: this last parameter is not yet - 24/02/2014 - deployed on the studio, but can be used already and will take effect immediately with the next update.

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

Game interface logic: yourgamename.js

2014-03-19T10:51:16Z

Sourisdudesert: /* Animations */

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

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

Note: the third parameter of dojo.place can take various interesting value: "first", "after", ... [http://dojotoolkit.org/reference-guide/1.7/dojo/place.html See full doc on 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 than "slideToObjectPos", 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: when you attach an HTML element with a new parent, you 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 )'''

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: if set to "true", the button is going blink to catch player's attention. Please don't abuse of blinking button.

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>

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

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

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

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

<pre>

// 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();
} );

</pre>

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 "<div id='myDlgContent'>" 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" => '<div>Some header</div>',
"footer" => '<div>Some footer</div>',
"closelabel" => 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)
*'''closelabel''': 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). NB: this last parameter is not yet - 24/02/2014 - deployed on the studio, but can be used already and will take effect immediately with the next update.

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

Logos

2014-02-12T21:14:22Z

Sourisdudesert: /* BGA buttons */

On this page you can find brand assets for Board Game Arena and easy way to create links to BGA.

Please use "right click + save image as" to download needed images.

= BGA buttons =

You can use buttons below as links to BGA website.

If you need a button that is not on the list please contact us (contact@boardgamearena.com).

== Language independent ==

[[File:bga_button.png]]

== English ==

Generic:

[[File:play_games_online_en.png]]

Play it online:

[[File:play_it_on_bga_en.png]]

== French ==

[[File:play_games_online_fr.png]]

== German ==

[[File:play_games_online_de.png]]

== Spanish ==

[[File:play_games_online_es.png]]

== Italian ==

[[File:play_games_online_it.png]]

== Chinese (traditional) ==

[[File:play_games_online_zh.png]]

== Chinese (simplified) ==

[[File:play_games_online_zh_cn.png]]

== Japanese ==

[[File:play_games_online_ja.png]]

= BGA logos =

== BGA transparent horizontal logo ==

(should be used on a white background):
[[File:BGA transparent horizontal logo.png]]

== BGA transparent horizontal white logo ==

(should be used on a black background):
[[File:BGA transparent horizontal white logo.png]]

== BGA transparent vertical logo ==

[[File:BGA_transparent_vertical_logo.png]]

== BGA icon ==

16x16:
[[File:BGA logo 16.png]]

75x75:
[[File:BGA logo 75.png]]

128x128:
[[File:BGA logo 128.png]]

512x512:
[[File:BGA logo 512.png]]

Logos

2014-02-12T21:08:32Z

Sourisdudesert: /* English */

On this page you can find brand assets for Board Game Arena and easy way to create links to BGA.

Please use "right click + save image as" to download needed images.

= BGA buttons =

You can use buttons below as links to BGA website:

== Language independent ==

[[File:bga_button.png]]

== English ==

Generic:

[[File:play_games_online_en.png]]

Play it online:

[[File:play_it_on_bga_en.png]]

== French ==

[[File:play_games_online_fr.png]]

== German ==

[[File:play_games_online_de.png]]

== Spanish ==

[[File:play_games_online_es.png]]

== Italian ==

[[File:play_games_online_it.png]]

== Chinese (traditional) ==

[[File:play_games_online_zh.png]]

== Chinese (simplified) ==

[[File:play_games_online_zh_cn.png]]

== Japanese ==

[[File:play_games_online_ja.png]]

= BGA logos =

== BGA transparent horizontal logo ==

(should be used on a white background):
[[File:BGA transparent horizontal logo.png]]

== BGA transparent horizontal white logo ==

(should be used on a black background):
[[File:BGA transparent horizontal white logo.png]]

== BGA transparent vertical logo ==

[[File:BGA_transparent_vertical_logo.png]]

== BGA icon ==

16x16:
[[File:BGA logo 16.png]]

75x75:
[[File:BGA logo 75.png]]

128x128:
[[File:BGA logo 128.png]]

512x512:
[[File:BGA logo 512.png]]

파일:Play it on bga en.png

2014-02-12T21:06:47Z

Sourisdudesert:

파일:Bga button.png

2014-02-12T21:06:36Z

Sourisdudesert:

Logos

2014-02-12T21:05:52Z

Sourisdudesert:

On this page you can find brand assets for Board Game Arena and easy way to create links to BGA.

Please use "right click + save image as" to download needed images.

= BGA buttons =

You can use buttons below as links to BGA website:

== English ==

[[File:play_games_online_en.png]]

== French ==

[[File:play_games_online_fr.png]]

== German ==

[[File:play_games_online_de.png]]

== Spanish ==

[[File:play_games_online_es.png]]

== Italian ==

[[File:play_games_online_it.png]]

== Chinese (traditional) ==

[[File:play_games_online_zh.png]]

== Chinese (simplified) ==

[[File:play_games_online_zh_cn.png]]

== Japanese ==

[[File:play_games_online_ja.png]]

= BGA logos =

== BGA transparent horizontal logo ==

(should be used on a white background):
[[File:BGA transparent horizontal logo.png]]

== BGA transparent horizontal white logo ==

(should be used on a black background):
[[File:BGA transparent horizontal white logo.png]]

== BGA transparent vertical logo ==

[[File:BGA_transparent_vertical_logo.png]]

== BGA icon ==

16x16:
[[File:BGA logo 16.png]]

75x75:
[[File:BGA logo 75.png]]

128x128:
[[File:BGA logo 128.png]]

512x512:
[[File:BGA logo 512.png]]

파일:Play games online zh cn.png

2014-02-12T21:03:01Z

Sourisdudesert:

파일:Play games online zh.png

2014-02-12T21:02:51Z

Sourisdudesert:

파일:Play games online ja.png

2014-02-12T21:02:37Z

Sourisdudesert:

파일:Play games online it.png

2014-02-12T21:02:28Z

Sourisdudesert:

파일:Play games online fr.png

2014-02-12T21:02:18Z

Sourisdudesert: uploaded a new version of "File:Play games online fr.png"

파일:Play games online fr.png

2014-02-12T21:02:08Z

Sourisdudesert:

파일:Play games online es.png

2014-02-12T21:02:00Z

Sourisdudesert:

파일:Play games online en.png

2014-02-12T21:01:50Z

Sourisdudesert:

파일:Play games online de.png

2014-02-12T21:01:39Z

Sourisdudesert:

Logos

2014-02-12T20:13:24Z

Sourisdudesert: /* BGA icon */

On this page you can find brand assets for Board Game Arena and easy way to create links to BGA.

Please use "right click + save image as" to download needed images.

== BGA transparent horizontal logo ==

(should be used on a white background):
[[File:BGA transparent horizontal logo.png]]

== BGA transparent horizontal white logo ==

(should be used on a black background):
[[File:BGA transparent horizontal white logo.png]]

== BGA transparent vertical logo ==

[[File:BGA_transparent_vertical_logo.png]]

== BGA icon ==

16x16:
[[File:BGA logo 16.png]]

75x75:
[[File:BGA logo 75.png]]

128x128:
[[File:BGA logo 128.png]]

512x512:
[[File:BGA logo 512.png]]

Logos

2014-02-12T20:13:07Z

Sourisdudesert:

파일:BGA logo 512.png

2014-02-12T20:12:08Z

Sourisdudesert:

파일:BGA logo 128.png

2014-02-12T20:12:01Z

Sourisdudesert:

파일:BGA logo 75.png

2014-02-12T20:11:53Z

Sourisdudesert:

파일:BGA logo 16.png

2014-02-12T20:11:45Z

Sourisdudesert:

Logos

2014-02-12T20:11:10Z

Sourisdudesert:

Logos

2014-02-12T20:10:37Z

Sourisdudesert: Created page with "On this page you can find brand assets for Board Game Arena. Please use "right click + save image as" to download needed images. == BGA transparent horizontal logo == (sho..."

On this page you can find brand assets for Board Game Arena.

Please use "right click + save image as" to download needed images.

== BGA transparent horizontal logo ==

(should be used on a white background):
[[File:BGA transparent horizontal logo.png]]

== BGA transparent horizontal white logo ==

(should be used on a black background):
[[File:BGA transparent horizontal white logo.png]]

== BGA transparent vertical logo ==

[[File:BGA_transparent_vertical_logo.png]]

파일:BGA transparent vertical logo.png

2014-02-12T20:10:18Z

Sourisdudesert:

파일:BGA transparent horizontal white logo.png

2014-02-12T20:09:09Z

Sourisdudesert:

파일:BGA transparent horizontal logo.png

2014-02-12T20:06:45Z

Sourisdudesert:

Moderationpolicy

2014-01-06T13:24:42Z

Sourisdudesert: /* About private jokes */

== General rules ==

=== Beyond a Reasonable Doubt ===

In case there is a any possible doubt, a player should be considered not guilty.

=== Moderators independance ===

Moderators must not process reports if they know the protagonists (author or targeted player). Playing online with the protagonist does not mean to "know" them. "Know" means: know them personally or playing with them online very regularly.

=== Appeal ===

Players has the right to appeal against the moderation decision, by forwarding received moderation email to "contact@boardgamearena.com".

They '''MUST''' explain in the email why the moderator did not respect the BGA moderation policy. If the explanation is not convincing, the email will be ignored. If the player is obviously guilty and if the moderation policy hasn't been violated, BGA admins will double the penalties.

=== Penalty grid ===

Moderators should respect the penalties grid as much as possible. However, they have the right to adjust the penalty depending on the gravity of the case. The following situation can lead moderators to increase the penalties:
* the player has been reported several times for the same type of case.
* the player wrong action can be obviously qualified by one or several of the following terms: racism, xenophobia, homophobia, sexism, and as a rule of thumb any type of discrimination against a particular category of people.
* on case there is a provocation, the penalty may be be reduced a little, and the author of the provocation may have a warning BUT, as everyone should keep quiet and polite even if there are provoked, this is a moderator choice.

=== Relapse ===

In case there is a relapse, the penalty increases exponentially.

This is the moderator job to determine the right penalty to apply in this case, considering the fact that the player has been warned by a first penalty.

Moderators should consider there is a relapse only if the new wrong action occurs AFTER the previous penalty has been applied and the associated moderation email has been sent.

Considering it's a lot of work to analyze reports about players who do the same action again and again, the "ban forever" penalty can be applied to any case if the player relapses.

=== Special urgency ban procedure ===

Whatever the case type, moderators has the right to ban a player from the website (forever) if this player set up a situation that is out of control and must be stopped within hours. This special procedure should only be used if there is an immediate danger for the community (ex: vandalism, flow of insults, massive spam, ...).

=== About private jokes ===

If a wrong action happened in a private circle (ex: at a game table, with no spectators), and if none of the present players reported the action, the moderator must consider this was a "private joke" and must not apply any penalty. In the contrary, if the wrong action is public (ex: post/comment on the wall), the moderator may consider this as a wrong action even if there is no report.

Note: in case a moderator discovers that this is obviously not a private joke and that something must be reported, the moderator is allowed to create a report for the case. However, in this case, this moderator is not allowed to judge the report.

=== Prescription ===

For operational reason, a report that is older than 2 weeks may be closed by moderators because it is too old.

=== Player profile influence ===

The player profile IS taken into account to determine if the player is guilty or not guilty. Moderators give more credit to players with a good profile than the other.

The player profile is NOT taken into account when choosing the penalty if the player is found guilty.

Good profile elements are:
* A good thumb up / thumb down ratio.
* Player is registered since a long time / has a lot of games played.
* Players is involved in the website (ex: realized translations).
* Player is supporting BGA (member of the club).

=== Incomplete reports ===

Analyzing reports takes a lot of time, and many reports are received. If any needed information is missing in the report, moderators may (and most of the time, should) close the report.

== Penalty grid ==

{| class="wikitable alternance centre"
|+ Titre
|-
! scope="col" | Category
! scope="col" | Case type
! scope="col" | Details
! scope="col" | Standard penalty
|-
! Insults
| Insults during a game, on table chat
| Must be present in the report: table ID, and the insults terms. If the insult is not in English, or if the insult is not obvious, the report author must specify why this is insulting.
| Devilkin 3 days for small insults and insanity, Devilkin 30 days for real insults. Smaller penalty (ex: 1 day) can be applied if this was obviously a stupid joke. In any case: the player should be warn that this is the last warning before ban.
|-
! Insults
| Insults on general chat
| Must be present in the report: the insult terms. If the insult is not in English, or if the insult is not obvious, the report author must specify why this is insulting.
| Devilkin 30 days for small insults and insanity, Devilkin forever for real insults. In any case: the player should be warn that this is the last warning before ban.
|-
! Insults
| Insults on public space (wall, forum, comments...)
| Must be present in the report: where to find the insult, the insult terms. If the insult is not in English, or if the insult is not obvious, the report author must specify why this is insulting.
| Devilkin 3 days for small insults and insanity, Devilkin 30 days for real insults. Smaller penalty (ex: 1 day) can be applied if this was obviously a stupid joke. In any case: the player should be warn that this is the last warning before ban.
|-
! Aggressive attitude
| Aggressive attitude during a game: can't wait the other player, provocation, ...
| As a rule of thumb: as long as there is no insult, this is not an issue: thumb down are the solution. BUT, if the player is really borderline and should be warned, a moderation action is needed.
| -1 to -10 reputation penalty. Moderators should explain that this is a small warning, and that a change of attitude is needed.
|-
! Avatar
| Inappropriate avatar: explicit sexual content, extreme violence, advertising...
| If needed, report author should explain why this is inappropriate. Avatar is really inappropriate in 3 cases:
1°) It can hurt underage players (explicit sexual content, extreme violence)
2°) This is advertisement / this violate some intellectual property
3°) The avatar contains a reference that discriminate a group of people (ex: nazi cross)
| Avatar immediate removal + Devilkin 3 days to devilkin forever depending on the gravity. In any case: the player should be warn that this is the last warning before ban. If the player obviously don't measure the meaning of the avatar, the penalty can be reduced.
|-
! Avatar
| Inappropriate username
| If needed, report author should explain why this is inappropriate. Username are inappropriate when this is obviously an insult for many people. Moderators shouldn't moderate a username that is insulting by accident in a language that is not widely used on BGA.
| Ban from the website. Moderators should explain that the player is welcome with another username on BGA. Note that if the player has a long seniority on BGA (=many games played), moderators should be very cautious on the case: if no one noticed the username until now, it is probably not inappropriate.
|-
! Table description
| Inappropriate table description
| If needed, report author should explain why this is inappropriate. Table description is inappropriate when it contains insults, insanity, or tend to discriminate a group of people.
| Devilkin 3 days for small insults and insanity, Devilkin 30 days for real insults. Smaller penalty (ex: 1 day) can be applied if this was obviously a stupid joke. In any case: the player should be warn that this is the last warning before ban.
|-
! Kingmaking
| Kingmaking action during a game
| The report must contains the table id, the exact move number, and the exact explanation why this is a kingmaking action. To declare a player guilty, the player must have played an obvious move against his own interest, and it has to be a good player (clues: his ELO, number of game played, ...). As the difference between a mistake and a kingmaking action is very tight, one kingmaking report is not enough to find a player guilty: only players who regularly play against their interest should be found guilty.
| -1 to -10 reputation penalty. Moderators should warn the player that this is a only small warning. Relapses can lead to higher reputation points penalties.
|-
! Bug exploit
| Exploit a known bug during a game
| The bug must have been reported in the forum, and an exact reference to this bug must be in the report, with the table id and the move number. Minor bugs that can be considered as "variants" are NOT concerned (ex: pick 4 cards instead of 3). Bugs that violate the spirit of the game are concerned.
| No penalty applies: if there is a bug that has been widely used for a game, a global ELO reset (or an ELO adjustment for players who exploited the bug) will be done.
|-
! Private information
| Some player gives some private information during the game
| Players have the right to pretend things during a game. As these infos could be true or false, and could be exploited by other players too, moderators should be cautious when judging these cases. This case concerns players that had a strong intent to kill the pleasure of the game by giving some private information during the game.
| -1 to -10 reputation penalty. Moderators should warn the player that this is a only small warning. Relapses can lead to higher reputation points penalties.
|-
! Multiple accounts
| A player is using multiple accounts (most of the time: to boost his ELO rank)
| The report must contains the usernames of all intimidated accounts, and the reason why the report author think that multiple accounts are used. It is very difficult to find out if different accounts corresponds to different person. For example: BGA accepts that multiple players plays from the same IP address, to allow people from the same family to play at the same table. In addition, some players are using multiple accounts, but these accounts are not playing together (which is acceptable). Strong tools are available for moderators to detect multiple accounts that are used the wrong way.
| For secondary accounts: ban forever. For main account: ELO reseted to 1500 / ELO penalty for all games.
|-
! Something else
| Spam / advertising / inappropriate links
| The player is using BGA for advertising. In particular: links not related to the purpose of the page, advertising for other online boardgaming websites, spam, ...
|
|-
! Something else
| Translation stealing / vandalism
| The player is writing inappropriate / poor quality translations (or writes a lot of very minor modifications to someone else translation) to gain free club membership,
| Immediate ban from the website (to avoid vandalism).
|-
! Something else
| Player is slow to play
| Players have the right to think as long as they do not go over their allotted time. If the player is slow on purpose, the good answer is: thumb down.
| No penalty
|-
! Something else
| Player quit the game before the end
| In this case, player automatically gets a ELO penalty + a red mark on his profile. There is no need to do something else.
| No penalty
|-

|}

Moderationpolicy

2014-01-06T12:23:54Z

Sourisdudesert: /* Penalty grid */

== General rules ==

=== Beyond a Reasonable Doubt ===

In case there is a any possible doubt, a player should be considered not guilty.

=== Moderators independance ===

Moderators must not process reports if they know the protagonists (author or targeted player). Playing online with the protagonist does not mean to "know" them. "Know" means: know them personally or playing with them online very regularly.

=== Appeal ===

Players has the right to appeal against the moderation decision, by forwarding received moderation email to "contact@boardgamearena.com".

They '''MUST''' explain in the email why the moderator did not respect the BGA moderation policy. If the explanation is not convincing, the email will be ignored. If the player is obviously guilty and if the moderation policy hasn't been violated, BGA admins will double the penalties.

=== Penalty grid ===

Moderators should respect the penalties grid as much as possible. However, they have the right to adjust the penalty depending on the gravity of the case. The following situation can lead moderators to increase the penalties:
* the player has been reported several times for the same type of case.
* the player wrong action can be obviously qualified by one or several of the following terms: racism, xenophobia, homophobia, sexism, and as a rule of thumb any type of discrimination against a particular category of people.
* on case there is a provocation, the penalty may be be reduced a little, and the author of the provocation may have a warning BUT, as everyone should keep quiet and polite even if there are provoked, this is a moderator choice.

=== Relapse ===

In case there is a relapse, the penalty increases exponentially.

This is the moderator job to determine the right penalty to apply in this case, considering the fact that the player has been warned by a first penalty.

Moderators should consider there is a relapse only if the new wrong action occurs AFTER the previous penalty has been applied and the associated moderation email has been sent.

Considering it's a lot of work to analyze reports about players who do the same action again and again, the "ban forever" penalty can be applied to any case if the player relapses.

=== Special urgency ban procedure ===

Whatever the case type, moderators has the right to ban a player from the website (forever) if this player set up a situation that is out of control and must be stopped within hours. This special procedure should only be used if there is an immediate danger for the community (ex: vandalism, flow of insults, massive spam, ...).

=== About private jokes ===

If a wrong action happened in a private circle (ex: at a game table, with no spectators), and if none of the present players reported the action, the moderator must consider this was a "private joke" and must not apply any penalty. In the contrary, if the wrong action is public (ex: post/comment on the wall), the moderator may consider this as a wrong action even if there is no report.

=== Prescription ===

For operational reason, a report that is older than 2 weeks may be closed by moderators because it is too old.

=== Player profile influence ===

The player profile IS taken into account to determine if the player is guilty or not guilty. Moderators give more credit to players with a good profile than the other.

The player profile is NOT taken into account when choosing the penalty if the player is found guilty.

Good profile elements are:
* A good thumb up / thumb down ratio.
* Player is registered since a long time / has a lot of games played.
* Players is involved in the website (ex: realized translations).
* Player is supporting BGA (member of the club).

=== Incomplete reports ===

Analyzing reports takes a lot of time, and many reports are received. If any needed information is missing in the report, moderators may (and most of the time, should) close the report.

== Penalty grid ==

{| class="wikitable alternance centre"
|+ Titre
|-
! scope="col" | Category
! scope="col" | Case type
! scope="col" | Details
! scope="col" | Standard penalty
|-
! Insults
| Insults during a game, on table chat
| Must be present in the report: table ID, and the insults terms. If the insult is not in English, or if the insult is not obvious, the report author must specify why this is insulting.
| Devilkin 3 days for small insults and insanity, Devilkin 30 days for real insults. Smaller penalty (ex: 1 day) can be applied if this was obviously a stupid joke. In any case: the player should be warn that this is the last warning before ban.
|-
! Insults
| Insults on general chat
| Must be present in the report: the insult terms. If the insult is not in English, or if the insult is not obvious, the report author must specify why this is insulting.
| Devilkin 30 days for small insults and insanity, Devilkin forever for real insults. In any case: the player should be warn that this is the last warning before ban.
|-
! Insults
| Insults on public space (wall, forum, comments...)
| Must be present in the report: where to find the insult, the insult terms. If the insult is not in English, or if the insult is not obvious, the report author must specify why this is insulting.
| Devilkin 3 days for small insults and insanity, Devilkin 30 days for real insults. Smaller penalty (ex: 1 day) can be applied if this was obviously a stupid joke. In any case: the player should be warn that this is the last warning before ban.
|-
! Aggressive attitude
| Aggressive attitude during a game: can't wait the other player, provocation, ...
| As a rule of thumb: as long as there is no insult, this is not an issue: thumb down are the solution. BUT, if the player is really borderline and should be warned, a moderation action is needed.
| -1 to -10 reputation penalty. Moderators should explain that this is a small warning, and that a change of attitude is needed.
|-
! Avatar
| Inappropriate avatar: explicit sexual content, extreme violence, advertising...
| If needed, report author should explain why this is inappropriate. Avatar is really inappropriate in 3 cases:
1°) It can hurt underage players (explicit sexual content, extreme violence)
2°) This is advertisement / this violate some intellectual property
3°) The avatar contains a reference that discriminate a group of people (ex: nazi cross)
| Avatar immediate removal + Devilkin 3 days to devilkin forever depending on the gravity. In any case: the player should be warn that this is the last warning before ban. If the player obviously don't measure the meaning of the avatar, the penalty can be reduced.
|-
! Avatar
| Inappropriate username
| If needed, report author should explain why this is inappropriate. Username are inappropriate when this is obviously an insult for many people. Moderators shouldn't moderate a username that is insulting by accident in a language that is not widely used on BGA.
| Ban from the website. Moderators should explain that the player is welcome with another username on BGA. Note that if the player has a long seniority on BGA (=many games played), moderators should be very cautious on the case: if no one noticed the username until now, it is probably not inappropriate.
|-
! Table description
| Inappropriate table description
| If needed, report author should explain why this is inappropriate. Table description is inappropriate when it contains insults, insanity, or tend to discriminate a group of people.
| Devilkin 3 days for small insults and insanity, Devilkin 30 days for real insults. Smaller penalty (ex: 1 day) can be applied if this was obviously a stupid joke. In any case: the player should be warn that this is the last warning before ban.
|-
! Kingmaking
| Kingmaking action during a game
| The report must contains the table id, the exact move number, and the exact explanation why this is a kingmaking action. To declare a player guilty, the player must have played an obvious move against his own interest, and it has to be a good player (clues: his ELO, number of game played, ...). As the difference between a mistake and a kingmaking action is very tight, one kingmaking report is not enough to find a player guilty: only players who regularly play against their interest should be found guilty.
| -1 to -10 reputation penalty. Moderators should warn the player that this is a only small warning. Relapses can lead to higher reputation points penalties.
|-
! Bug exploit
| Exploit a known bug during a game
| The bug must have been reported in the forum, and an exact reference to this bug must be in the report, with the table id and the move number. Minor bugs that can be considered as "variants" are NOT concerned (ex: pick 4 cards instead of 3). Bugs that violate the spirit of the game are concerned.
| No penalty applies: if there is a bug that has been widely used for a game, a global ELO reset (or an ELO adjustment for players who exploited the bug) will be done.
|-
! Private information
| Some player gives some private information during the game
| Players have the right to pretend things during a game. As these infos could be true or false, and could be exploited by other players too, moderators should be cautious when judging these cases. This case concerns players that had a strong intent to kill the pleasure of the game by giving some private information during the game.
| -1 to -10 reputation penalty. Moderators should warn the player that this is a only small warning. Relapses can lead to higher reputation points penalties.
|-
! Multiple accounts
| A player is using multiple accounts (most of the time: to boost his ELO rank)
| The report must contains the usernames of all intimidated accounts, and the reason why the report author think that multiple accounts are used. It is very difficult to find out if different accounts corresponds to different person. For example: BGA accepts that multiple players plays from the same IP address, to allow people from the same family to play at the same table. In addition, some players are using multiple accounts, but these accounts are not playing together (which is acceptable). Strong tools are available for moderators to detect multiple accounts that are used the wrong way.
| For secondary accounts: ban forever. For main account: ELO reseted to 1500 / ELO penalty for all games.
|-
! Something else
| Spam / advertising / inappropriate links
| The player is using BGA for advertising. In particular: links not related to the purpose of the page, advertising for other online boardgaming websites, spam, ...
|
|-
! Something else
| Translation stealing / vandalism
| The player is writing inappropriate / poor quality translations (or writes a lot of very minor modifications to someone else translation) to gain free club membership,
| Immediate ban from the website (to avoid vandalism).
|-
! Something else
| Player is slow to play
| Players have the right to think as long as they do not go over their allotted time. If the player is slow on purpose, the good answer is: thumb down.
| No penalty
|-
! Something else
| Player quit the game before the end
| In this case, player automatically gets a ELO penalty + a red mark on his profile. There is no need to do something else.
| No penalty
|-

|}

Moderationpolicy

2014-01-06T12:17:50Z

Sourisdudesert: /* Penalty grid */

== General rules ==

=== Beyond a Reasonable Doubt ===

In case there is a any possible doubt, a player should be considered not guilty.

=== Moderators independance ===

Moderators must not process reports if they know the protagonists (author or targeted player). Playing online with the protagonist does not mean to "know" them. "Know" means: know them personally or playing with them online very regularly.

=== Appeal ===

Players has the right to appeal against the moderation decision, by forwarding received moderation email to "contact@boardgamearena.com".

They '''MUST''' explain in the email why the moderator did not respect the BGA moderation policy. If the explanation is not convincing, the email will be ignored. If the player is obviously guilty and if the moderation policy hasn't been violated, BGA admins will double the penalties.

=== Penalty grid ===

Moderators should respect the penalties grid as much as possible. However, they have the right to adjust the penalty depending on the gravity of the case. The following situation can lead moderators to increase the penalties:
* the player has been reported several times for the same type of case.
* the player wrong action can be obviously qualified by one or several of the following terms: racism, xenophobia, homophobia, sexism, and as a rule of thumb any type of discrimination against a particular category of people.
* on case there is a provocation, the penalty may be be reduced a little, and the author of the provocation may have a warning BUT, as everyone should keep quiet and polite even if there are provoked, this is a moderator choice.

=== Relapse ===

In case there is a relapse, the penalty increases exponentially.

This is the moderator job to determine the right penalty to apply in this case, considering the fact that the player has been warned by a first penalty.

Moderators should consider there is a relapse only if the new wrong action occurs AFTER the previous penalty has been applied and the associated moderation email has been sent.

Considering it's a lot of work to analyze reports about players who do the same action again and again, the "ban forever" penalty can be applied to any case if the player relapses.

=== Special urgency ban procedure ===

Whatever the case type, moderators has the right to ban a player from the website (forever) if this player set up a situation that is out of control and must be stopped within hours. This special procedure should only be used if there is an immediate danger for the community (ex: vandalism, flow of insults, massive spam, ...).

=== About private jokes ===

If a wrong action happened in a private circle (ex: at a game table, with no spectators), and if none of the present players reported the action, the moderator must consider this was a "private joke" and must not apply any penalty. In the contrary, if the wrong action is public (ex: post/comment on the wall), the moderator may consider this as a wrong action even if there is no report.

=== Prescription ===

For operational reason, a report that is older than 2 weeks may be closed by moderators because it is too old.

=== Player profile influence ===

The player profile IS taken into account to determine if the player is guilty or not guilty. Moderators give more credit to players with a good profile than the other.

The player profile is NOT taken into account when choosing the penalty if the player is found guilty.

Good profile elements are:
* A good thumb up / thumb down ratio.
* Player is registered since a long time / has a lot of games played.
* Players is involved in the website (ex: realized translations).
* Player is supporting BGA (member of the club).

=== Incomplete reports ===

Analyzing reports takes a lot of time, and many reports are received. If any needed information is missing in the report, moderators may (and most of the time, should) close the report.

== Penalty grid ==

{| class="wikitable alternance centre"
|+ Titre
|-
! scope="col" | Category
! scope="col" | Case type
! scope="col" | Details
! scope="col" | Standard penalty
|-
! Insults
| Insults during a game, on table chat
| Must be present in the report: table ID, and the insults terms. If the insult is not in English, or if the insult is not obvious, the report author must specify why this is insulting.
| Devilkin 3 days for small insults and insanity, Devilkin 30 days for real insults. Smaller penalty (ex: 1 day) can be applied if this was obviously a stupid joke. In any case: the player should be warn that this is the last warning before ban.
|-
! Insults
| Insults on general chat
| Must be present in the report: the insult terms. If the insult is not in English, or if the insult is not obvious, the report author must specify why this is insulting.
| Devilkin 30 days for small insults and insanity, Devilkin forever for real insults. In any case: the player should be warn that this is the last warning before ban.
|-
! Insults
| Insults on public space (wall, forum, comments...)
| Must be present in the report: where to find the insult, the insult terms. If the insult is not in English, or if the insult is not obvious, the report author must specify why this is insulting.
| Devilkin 3 days for small insults and insanity, Devilkin 30 days for real insults. Smaller penalty (ex: 1 day) can be applied if this was obviously a stupid joke. In any case: the player should be warn that this is the last warning before ban.
|-
! Aggressive attitude
| Aggressive attitude during a game: can't wait the other player, provocation, ...
| As a rule of thumb: as long as there is no insult, this is not an issue: thumb down are the solution. BUT, if the player is really borderline and should be warned, a moderation action is needed.
| -1 to -10 reputation penalty. Moderators should explain that this is a small warning, and that a change of attitude is needed.
|-
! Avatar
| Inappropriate avatar: explicit sexual content, extreme violence, advertising...
| If needed, report author should explain why this is inappropriate. Avatar is really inappropriate in 3 cases:
1°) It can hurt underage players (explicit sexual content, extreme violence)
2°) This is advertisement / this violate some intellectual property
3°) The avatar contains a reference that discriminate a group of people (ex: nazi cross)
| Avatar immediate removal + Devilkin 3 days to devilkin forever depending on the gravity. In any case: the player should be warn that this is the last warning before ban. If the player obviously don't measure the meaning of the avatar, the penalty can be reduced.
|-
! Avatar
| Inappropriate username
| If needed, report author should explain why this is inappropriate. Username are inappropriate when this is obviously an insult for many people. Moderators shouldn't moderate a username that is insulting by accident in a language that is not widely used on BGA.
| Ban from the website. Moderators should explain that the player is welcome with another username on BGA. Note that if the player has a long seniority on BGA (=many games played), moderators should be very cautious on the case: if no one noticed the username until now, it is probably not inappropriate.
|-
! Table description
| Inappropriate table description
| If needed, report author should explain why this is inappropriate. Table description is inappropriate when it contains insults, insanity, or tend to discriminate a group of people.
| Devilkin 3 days for small insults and insanity, Devilkin 30 days for real insults. Smaller penalty (ex: 1 day) can be applied if this was obviously a stupid joke. In any case: the player should be warn that this is the last warning before ban.
|-
! Kingmaking
| Kingmaking action during a game
| The report must contains the table id, the exact move number, and the exact explanation why this is a kingmaking action. To declare a player guilty, the player must have played an obvious move against his own interest, and it has to be a good player (clues: his ELO, number of game played, ...). As the difference between a mistake and a kingmaking action is very tight, one kingmaking report is not enough to find a player guilty: only players who regularly play against their interest should be found guilty.
| -1 to -10 reputation penalty. Moderators should warn the player that this is a only small warning. Relapses can lead to higher reputation points penalties.
|-
! Bug exploit
| Exploit a known bug during a game
| The bug must have been reported in the forum, and an exact reference to this bug must be in the report, with the table id and the move number. Minor bugs that can be considered as "variants" are NOT concerned (ex: pick 4 cards instead of 3). Bugs that violate the spirit of the game are concerned.
| No penalty applies: if there is a bug that has been widely used for a game, a global ELO reset (or an ELO adjustment for players who exploited the bug) will be done.
|-
! Private information
| Some player gives some private information during the game
| Players have the right to pretend things during a game. As these infos could be true or false, and could be exploited by other players too, moderators should be cautious when judging these cases. This case concerns players that had a strong intent to kill the pleasure of the game by giving some private information during the game.
| -1 to -10 reputation penalty. Moderators should warn the player that this is a only small warning. Relapses can lead to higher reputation points penalties.
|-
! Multiple accounts
| A player is using multiple accounts (most of the time: to boost his ELO rank)
| The report must contains the usernames of all intimidated accounts, and the reason why the report author think that multiple accounts are used. It is very difficult to find out if different accounts corresponds to different person. For example: BGA accepts that multiple players plays from the same IP address, to allow people from the same family to play at the same table. In addition, some players are using multiple accounts, but these accounts are not playing together (which is acceptable). Strong tools are available for moderators to detect multiple accounts that are used the wrong way.
| For secondary accounts: ban forever. For main account: ELO reseted to 1500 / ELO penalty for all games.
|-
! Something else
| Translation stealing / vandalism
| The player is writing inappropriate / poor quality translations (or writes a lot of very minor modifications to someone else translation) to gain free club membership,
| Immediate ban from the website (to avoid vandalism).
|-
! Something else
| Player is slow to play
| Players have the right to think as long as they do not go over their allotted time. If the player is slow on purpose, the good answer is: thumb down.
| No penalty
|-
! Something else
| Player quit the game before the end
| In this case, player automatically gets a ELO penalty + a red mark on his profile. There is no need to do something else.
| No penalty
|-

|}

Your game state machine: states.inc.php

2014-01-06T09:09:19Z

Sourisdudesert: /* args */

This file describes the game states machine of your game (all the game states properties, and the transitions to get from one state to another).

Important: to understand the game state machine, the best is to read this presentation first:

[http://www.slideshare.net/boardgamearena/bga-studio-focus-on-bga-game-state-machine Focus on BGA game state machine]

== Overall structure ==

The machine states is described by a PHP associative array.

Example:

<pre>
$machinestates = array(

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

// Note: ID=2 => your first state

2 => array(
"name" => "playerTurn",
"description" => clienttranslate('${actplayer} must play a card or pass'),
"descriptionmyturn" => clienttranslate('${you} must play a card or pass'),
"type" => "activeplayer",
"possibleactions" => array( "playCard", "pass" ),
"transitions" => array( "playCard" => 2, "pass" => 2 )
),
</pre>

== Syntax ==

=== id ===

The keys determine game states IDs (in the example above: 1 and 2).

IDs must be positive integers.

ID=1 is reserved for the first game state and should not be used (and you must not modify it).

ID=99 is reserved for the last game state of the game (end of the game) (and you must not modify it).

Note: you may use any ID, even ID greater than 100. But you cannot use 1 and 99.

Note²: You can't of course use the same ID twice.

=== name ===

(mandatory)

The name of a game state is used to identify it in your game logic.

Several game states can share the same name, however this is not recommended.

PHP example:
<pre>

// Get current game state
$state = $this->gamestate->state();
if( $state['name'] == 'myGameState' )
{
...
}

</pre>

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

switch( stateName )
case 'myGameState':

// Do some stuff at the beginning at this game state
....

break;
</pre>

=== type ===

(mandatory)

You can use 3 types of game states:
* activeplayer (1 player is active and must play)
* multipleactiveplayer (1..N players can be active and must play)
* game (no player is active. This is a transitional state to do something automatic specified by game rules)

=== description ===

(mandatory)

The description is the string that is displayed in the main action bar (top of the screen) when the state is active.

When a string is specified as a description, you must use "clienttranslate" in order the string can be translate on the client side:

<pre>
"description" => clienttranslate('${actplayer} must play a card or pass'),
</pre>

In the description string, you can use ${actplayer} to refer to the active player.

You can also use custom arguments in your description. These custom arguments correspond to values returned by your "args" PHP method (see below "args" field).

Example of custom field:
<pre>

In states.inc.php:
"description" => clienttranslate('${actplayer} must choose ${nbr} identical energies'),
"args" => "argMyArgumentMethod"

In mygame.game.php:
function argMyArgumentMethod()
{
return array(
'nbr' => 2 // In this case ${nbr} in the description will be replaced by "2"
);
}
</pre>

Note: You may specify an empty string ("") here if it never happens that the game remains in this state (ie: if this state immediately jump to another state when activated).

Note²: Usually, you specify a string for "activeplayer" and "multipleactiveplayer" game states, and you specify an empty string for "game" game states. BUT, if you are using synchronous notifications, the client can remains few seconds on a "game" type game state, and in this case this may be useful to display a description in the status bar during this state.

=== descriptionmyturn ===

(mandatory for "activeplayer" and "multipleactiveplayer" game states type)

"descriptionmyturn" has exactly the same role and properties than "description", except that this value is displayed to the current active player - or to all active players in case of a multipleactiveplayer game state.

In general, we have this situation:

<pre>
"description" => clienttranslate('${actplayer} can take some actions'),
"descriptionmyturn" => clienttranslate('${you} can take some actions'),
</pre>

Note: you can use ${you} in description my turn in order the description can display "You" instead of the name of the player.

=== action ===

(mandatory for "game" game state type)

"action" specify a PHP method to call when entering into this game state.

Example:
<pre>
In states.inc.php:
28 => array(
"name" => "startPlayerTurn",
"description" => '',
"type" => "game",
"action" => "stStartPlayerTurn",

In mygame.game.php:
function stStartPlayerTurn()
{
// ... do something at the beginning of this game state
</pre>

Usually, for "game" game state type, the action method is used to do some automatic stuff specified by the rules (ex: check victory conditions, deal cards for a new round, go to the next player...) and then jump to another game state.

Note: a BGA convention specify that PHP method called with "action" are prefixed by "st".

=== transitions ===

(mandatory)

With "transition" you specify in which game state you can jump from a given game state.

Example:
<pre>
25 => array(
"name" => "myGameState",
"transitions" => array( "nextPlayer" => 27, "endRound" => 39 ),
....
}
</pre>

In the example above, if "myGameState" is the current active game state, I can jump to game state with ID 27, or game state with ID 39.

Example to jump to ID 27:
<pre>
In mygame.game.php:
$this->gamestate->nextState( "nextPlayer" );
</pre>

Important: "nextPlayer" is the name of the transition, and NOT the name of the target game state. Several transitions can lead to the same game state.

Note: if you have only 1 transition, you may give it an empty name.

Example:
<pre>
In states.inc.php:
"transitions" => array( "" => 27 ),

In mygame.game.php:
$this->gamestate->nextState( ); // We don't need to specify a transition as there is only one here
</pre>

=== possibleactions ===

(mandatory for "activeplayer" and "multipleactiveplayer" game states)

"possibleactions" defines the actions possible by the players at this game state.

By defining "possibleactions", you make sure players can't do actions that they are not allowed to do at this game states.

Example:

<pre>
In states.game.php:
"possibleactions" => array( "playCard", "pass" ),

In mygame.game.php:
function playCard( ...)
{
self::checkAction( "playCard" ); // Will failed if "playCard" is not specified in "possibleactions" in current game state.

....

In mygame.js:
playCard: function( ... )
{
if( this.checkAction( "playCard" ) ) // Will failed if "playCard" is not specified in "possibleactions" in current game state.
{ return ; }

....

</pre>

=== args ===

(optional)

From time to time, it happens that you need some information on the client side (ie : for your game interface) only for a specific game state.

Example 1 : for Reversi, the list of possible moves during playerTurn state.
Example 2 : in Caylus, the number of remaining king's favor to choose in the state where the player is choosing a favor.
Example 3 : in Can't stop, the list of possible die combination to be displayed to the active player in order he can choose among them.

In such a situation, you can specify a method name as the « args » argument for your game state. This method must get some piece of information about the game (ex : for Reversi, the possible moves) and return them.

Thus, this data can be transmitted to the clients and used by the clients to display it. It should always be an associative array.

Let's see a complete example using args with « Reversi » game :

In states.inc.php, we specify some « args » argument for gamestate « playerTurn » :
<pre>
10 => array(
"name" => "playerTurn",
"description" => clienttranslate('${actplayer} must play a disc'),
"descriptionmyturn" => clienttranslate('${you} must play a disc'),
"type" => "activeplayer",
"args" => "argPlayerTurn", <================================== HERE
"possibleactions" => array( 'playDisc' ),
"transitions" => array( "playDisc" => 11, "zombiePass" => 11 )
),
</pre>

It corresponds to a « argPlayerTurn » method in our PHP code (reversi.game.php):
<pre>
function argPlayerTurn()
{
return array(
'possibleMoves' => self::getPossibleMoves()
);
}
</pre>

Then, when we enter into « playerTurn » game state on the client side, we can highlight the possible moves on the board using information returned by argPlayerTurn :

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

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

Note: you can also use values returned by your "args" method to have some custom values in your "description"/"descriptionmyturn" (see above).

Note: as a BGA convention, PHP methods called with "args" are prefixed by "arg" (ex: argPlayerTurn).

==== Private infos in args ====

By default, all data provided through this method are PUBLIC TO ALL PLAYERS. Please do not send any private data with this method, as a cheater could see it even it is not used explicitly by the game interface logic.

This is although possible to specify that some data should be sent to some specific players only:

Example 1: send an information to active player(s) only:

<pre>
function argPlayerTurn()
{
return array(
'_private' => array( // Using "_private" keyword, all data inside this array will be made private

'active' => array( // Using "active" keyword inside "_private", you select active player(s)
'somePrivateData' => self::getSomePrivateData() // will be send only to active player(s)
)
),

'possibleMoves' => self::getPossibleMoves() // will be send to all players
);
}
</pre>

Example 2: send an information to a specific player (<specific_player_id>) only:

<pre>
function argPlayerTurn()
{
return array(
'_private' => array( // Using "_private" keyword, all data inside this array will be made private

<specific_player_id> => array( // you select one specific player with its id
'somePrivateData' => self::getSomePrivateData() // will be send only to <specific_player_id>
)
),

'possibleMoves' => self::getPossibleMoves() // will be send to all players
);
}
</pre>

IMPORTANT: in certain situation (ex: multipleactiveplayer game state) these "private data" features can have a big performance impact. Please do not use if not needed.

=== updateGameProgression ===

(optional)

IF you specify "updateGameProgression => true" in a game state, your "getGameProgression" PHP method will be called at the beginning of this game state - and thus the game progression of the game will be updated.

At least one of your game state (any of them) must specify updateGameProgression=>true.

Main game logic: yourgamename.game.php

2014-01-06T09:00:34Z

Sourisdudesert: /* File Structure */

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

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

== Accessing player informations ==

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

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

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

; loadPlayersBasicInfos()
: Get an associative array with generic data about players (ie: not game specific data).
: The key of the associative array is the player id.
: The content of each value is:
: * player_name
: * player_color (ex: ff0000)

; getCurrentPlayerId()
: Get the "current_player". The current player is the one from which the action originated (the one who send the request).
: '''Be careful''': It is not always the active player.
: In general, you shouldn't use this method, unless you are in "multiplayer" state.

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

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

; isCurrentPlayerZombie()
: Check the "current_player" zombie status. If true, player leave the game.

== Accessing database ==

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

'''IMPORTANT'''

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

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

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

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

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

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

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

</pre>

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

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

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

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

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

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

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

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

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

</pre>

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

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

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

; escapeStringForDB( $string )
: You must use this function on every string type data in your database that contains unsafe data.
: (unsafe = can be modified by a player).
: This method makes sure that no SQL injection will be done through the string used.

<pre>
self::getObjectFromDB( "SELECT player_id id, player_name name, player_color color FROM player WHERE player_id='1234'" );

Result:
array(
'id' => 1234,
'name' => 'myuser1',
'color' => 'ff0000'
)

</pre>

; function getNonEmptyObjectFromDB( $sql )
: Idem, but raise an exception if the query doesn't return exactly one row

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

== Use globals ==

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

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

'''initGameStateLabels'''

This method is located at the beginning of your game logic. This is the place you defines the globals used in your game logic, by assigning them IDs.

You can define up to 89 globals, with IDs from 10 to 89. You must NOT use globals outside this range as globals are used by other components of the framework.

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

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

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

'''getGameStateValue( $value_label )'''

Retrieve the current value of a global.

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

Set the current value of a global.

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

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

Return the final value of the global.

== Game states and active players ==

; checkAction( $actionName, $bThrowException=true )
: Check if action is valid regarding current game state (exception if fails)
: The action is valid if it is listed as a "possibleactions" in the current game state (see game state description).
: This method MUST be called in the first place in ALL your PHP methods that handle players action, in order to make sure a player can't do an action when the rules disallow it at this moment of the game.
: if "bThrowException" is set to "false", the function return false in case of failure instead of throwing and exception. This is useful when several actions are possible in order to test each of them without throwing exceptions.

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

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

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

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

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

; $this->gamestate->setPlayersMultiactive( $players, $next_state )
: Make a specific list of players active during a multiactive gamestate.
: Bare in mind it doesn't deactivate other previously active players.
: "players" is the array of player id that should be made active.
: In case "players" is empty, the method trigger the "next_state" transition to go to the next game state.

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

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

== Players turn order ==

'''getNextPlayerTable()'''

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

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

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

'''getPrevPlayerTable()'''

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

'''getPlayerAfter( $player_id )'''

Get player playing after given player in natural playing order.

'''getPlayerBefore( $player_id )'''

Get player playing before given player in natural playing order.

== Notify players ==

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

'''IMPORTANT'''

Notifications are sent at the very end of the request, when it ends normally. It means that if you throw an exception for any reason (ex: move not allowed), no notifications will be sent to players.

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

Send a notification to all players of the game.

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

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

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

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

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

You can use arguments in your notification_log strings, that refers to values defines in the "notification_args" argument (see below).

Note: you CAN use some HTML inside your notification log, and it is working. However:
_ pay attention to keep the log clear.
_ try to not include some HTML tags inside the "clienttranslate" method, otherwise it will make the translators work more difficult. You can use a notification argument instead, and provide your HTML through this argument.

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

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

Complete notifyAllPlayers example (from "Reversi"):

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

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

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

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

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

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

== Game statistics ==

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

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

'''initStat( $table_or_player, $name, $value, $player_id=null )'''
Create a statistic entry for the specified statistics with a default value.
This method must be called for each statistics of your game, in your setupNewGame method.

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

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

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

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

Set a statistic value.

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

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

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

Increment (or decrement) specified statistic value. Same behavior as above.

== Translations ==

See [[Translations]]

== Manage player scores and Tie breaker ==

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

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

Examples:
<pre>

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

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

</pre>

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

'''Tie breaker'''

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

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

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

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

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

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

== Reflexion time ==

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

== Managing errors and exceptions ==

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

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

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

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

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

== Zombie mode ==

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

While developing your zombie mode, keep in mind that:
* Do not refer to the rules, because this situation is not planned by the rules.
* Try to figure that you are playing with your friends and one of them has to leave: how can we finish the game without killing the spirit of the game?
* The idea is NOT to develop an artificial intelligence for the game.

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

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

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

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

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

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

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

== Player elimination ==

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

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

Usage:

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

Main game logic: yourgamename.game.php

2014-01-06T08:53:15Z

Sourisdudesert: /* Player elimination */

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

== 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:
* EmptyGame (constructor): where you define global variables.
* setupNewGame: initial setup of the game.
* getAllDatas: where you retrieve all game data during a complete reload of the game.
* getGameProgression: where you compute the game progression indicator.
* Utility functions: your utility functions.
* Player actions: the entry points for players actions.
* Game state arguments: methods to return additional data on specific game states.
* Game state actions: the logic to run when entering a new game state.
* zombieTurn: what to do it's the turn of a zombie player.

== Accessing player informations ==

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

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

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

; loadPlayersBasicInfos()
: Get an associative array with generic data about players (ie: not game specific data).
: The key of the associative array is the player id.
: The content of each value is:
: * player_name
: * player_color (ex: ff0000)

; getCurrentPlayerId()
: Get the "current_player". The current player is the one from which the action originated (the one who send the request).
: '''Be careful''': It is not always the active player.
: In general, you shouldn't use this method, unless you are in "multiplayer" state.

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

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

; isCurrentPlayerZombie()
: Check the "current_player" zombie status. If true, player leave the game.

== Accessing database ==

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

'''IMPORTANT'''

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

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

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

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

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

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

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

</pre>

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

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

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

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

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

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

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

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

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

</pre>

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

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

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

; escapeStringForDB( $string )
: You must use this function on every string type data in your database that contains unsafe data.
: (unsafe = can be modified by a player).
: This method makes sure that no SQL injection will be done through the string used.

<pre>
self::getObjectFromDB( "SELECT player_id id, player_name name, player_color color FROM player WHERE player_id='1234'" );

Result:
array(
'id' => 1234,
'name' => 'myuser1',
'color' => 'ff0000'
)

</pre>

; function getNonEmptyObjectFromDB( $sql )
: Idem, but raise an exception if the query doesn't return exactly one row

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

== Use globals ==

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

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

'''initGameStateLabels'''

This method is located at the beginning of your game logic. This is the place you defines the globals used in your game logic, by assigning them IDs.

You can define up to 89 globals, with IDs from 10 to 89. You must NOT use globals outside this range as globals are used by other components of the framework.

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

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

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

'''getGameStateValue( $value_label )'''

Retrieve the current value of a global.

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

Set the current value of a global.

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

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

Return the final value of the global.

== Game states and active players ==

; checkAction( $actionName, $bThrowException=true )
: Check if action is valid regarding current game state (exception if fails)
: The action is valid if it is listed as a "possibleactions" in the current game state (see game state description).
: This method MUST be called in the first place in ALL your PHP methods that handle players action, in order to make sure a player can't do an action when the rules disallow it at this moment of the game.
: if "bThrowException" is set to "false", the function return false in case of failure instead of throwing and exception. This is useful when several actions are possible in order to test each of them without throwing exceptions.

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

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

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

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

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

; $this->gamestate->setPlayersMultiactive( $players, $next_state )
: Make a specific list of players active during a multiactive gamestate.
: Bare in mind it doesn't deactivate other previously active players.
: "players" is the array of player id that should be made active.
: In case "players" is empty, the method trigger the "next_state" transition to go to the next game state.

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

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

== Players turn order ==

'''getNextPlayerTable()'''

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

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

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

'''getPrevPlayerTable()'''

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

'''getPlayerAfter( $player_id )'''

Get player playing after given player in natural playing order.

'''getPlayerBefore( $player_id )'''

Get player playing before given player in natural playing order.

== Notify players ==

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

'''IMPORTANT'''

Notifications are sent at the very end of the request, when it ends normally. It means that if you throw an exception for any reason (ex: move not allowed), no notifications will be sent to players.

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

Send a notification to all players of the game.

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

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

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

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

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

You can use arguments in your notification_log strings, that refers to values defines in the "notification_args" argument (see below).

Note: you CAN use some HTML inside your notification log, and it is working. However:
_ pay attention to keep the log clear.
_ try to not include some HTML tags inside the "clienttranslate" method, otherwise it will make the translators work more difficult. You can use a notification argument instead, and provide your HTML through this argument.

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

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

Complete notifyAllPlayers example (from "Reversi"):

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

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

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

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

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

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

== Game statistics ==

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

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

'''initStat( $table_or_player, $name, $value, $player_id=null )'''
Create a statistic entry for the specified statistics with a default value.
This method must be called for each statistics of your game, in your setupNewGame method.

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

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

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

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

Set a statistic value.

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

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

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

Increment (or decrement) specified statistic value. Same behavior as above.

== Translations ==

See [[Translations]]

== Manage player scores and Tie breaker ==

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

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

Examples:
<pre>

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

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

</pre>

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

'''Tie breaker'''

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

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

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

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

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

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

== Reflexion time ==

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

== Managing errors and exceptions ==

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

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

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

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

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

== Zombie mode ==

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

While developing your zombie mode, keep in mind that:
* Do not refer to the rules, because this situation is not planned by the rules.
* Try to figure that you are playing with your friends and one of them has to leave: how can we finish the game without killing the spirit of the game?
* The idea is NOT to develop an artificial intelligence for the game.

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

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

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

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

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

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

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

== Player elimination ==

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

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

Usage:

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

Main game logic: yourgamename.game.php

2014-01-06T08:45:43Z

Sourisdudesert:

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

== 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:
* EmptyGame (constructor): where you define global variables.
* setupNewGame: initial setup of the game.
* getAllDatas: where you retrieve all game data during a complete reload of the game.
* getGameProgression: where you compute the game progression indicator.
* Utility functions: your utility functions.
* Player actions: the entry points for players actions.
* Game state arguments: methods to return additional data on specific game states.
* Game state actions: the logic to run when entering a new game state.
* zombieTurn: what to do it's the turn of a zombie player.

== Accessing player informations ==

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

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

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

; loadPlayersBasicInfos()
: Get an associative array with generic data about players (ie: not game specific data).
: The key of the associative array is the player id.
: The content of each value is:
: * player_name
: * player_color (ex: ff0000)

; getCurrentPlayerId()
: Get the "current_player". The current player is the one from which the action originated (the one who send the request).
: '''Be careful''': It is not always the active player.
: In general, you shouldn't use this method, unless you are in "multiplayer" state.

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

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

; isCurrentPlayerZombie()
: Check the "current_player" zombie status. If true, player leave the game.

== Accessing database ==

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

'''IMPORTANT'''

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

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

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

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

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

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

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

</pre>

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

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

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

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

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

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

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

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

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

</pre>

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

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

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

; escapeStringForDB( $string )
: You must use this function on every string type data in your database that contains unsafe data.
: (unsafe = can be modified by a player).
: This method makes sure that no SQL injection will be done through the string used.

<pre>
self::getObjectFromDB( "SELECT player_id id, player_name name, player_color color FROM player WHERE player_id='1234'" );

Result:
array(
'id' => 1234,
'name' => 'myuser1',
'color' => 'ff0000'
)

</pre>

; function getNonEmptyObjectFromDB( $sql )
: Idem, but raise an exception if the query doesn't return exactly one row

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

== Use globals ==

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

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

'''initGameStateLabels'''

This method is located at the beginning of your game logic. This is the place you defines the globals used in your game logic, by assigning them IDs.

You can define up to 89 globals, with IDs from 10 to 89. You must NOT use globals outside this range as globals are used by other components of the framework.

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

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

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

'''getGameStateValue( $value_label )'''

Retrieve the current value of a global.

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

Set the current value of a global.

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

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

Return the final value of the global.

== Game states and active players ==

; checkAction( $actionName, $bThrowException=true )
: Check if action is valid regarding current game state (exception if fails)
: The action is valid if it is listed as a "possibleactions" in the current game state (see game state description).
: This method MUST be called in the first place in ALL your PHP methods that handle players action, in order to make sure a player can't do an action when the rules disallow it at this moment of the game.
: if "bThrowException" is set to "false", the function return false in case of failure instead of throwing and exception. This is useful when several actions are possible in order to test each of them without throwing exceptions.

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

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

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

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

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

; $this->gamestate->setPlayersMultiactive( $players, $next_state )
: Make a specific list of players active during a multiactive gamestate.
: Bare in mind it doesn't deactivate other previously active players.
: "players" is the array of player id that should be made active.
: In case "players" is empty, the method trigger the "next_state" transition to go to the next game state.

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

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

== Players turn order ==

'''getNextPlayerTable()'''

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

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

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

'''getPrevPlayerTable()'''

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

'''getPlayerAfter( $player_id )'''

Get player playing after given player in natural playing order.

'''getPlayerBefore( $player_id )'''

Get player playing before given player in natural playing order.

== Notify players ==

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

'''IMPORTANT'''

Notifications are sent at the very end of the request, when it ends normally. It means that if you throw an exception for any reason (ex: move not allowed), no notifications will be sent to players.

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

Send a notification to all players of the game.

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

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

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

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

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

You can use arguments in your notification_log strings, that refers to values defines in the "notification_args" argument (see below).

Note: you CAN use some HTML inside your notification log, and it is working. However:
_ pay attention to keep the log clear.
_ try to not include some HTML tags inside the "clienttranslate" method, otherwise it will make the translators work more difficult. You can use a notification argument instead, and provide your HTML through this argument.

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

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

Complete notifyAllPlayers example (from "Reversi"):

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

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

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

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

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

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

== Game statistics ==

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

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

'''initStat( $table_or_player, $name, $value, $player_id=null )'''
Create a statistic entry for the specified statistics with a default value.
This method must be called for each statistics of your game, in your setupNewGame method.

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

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

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

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

Set a statistic value.

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

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

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

Increment (or decrement) specified statistic value. Same behavior as above.

== Translations ==

See [[Translations]]

== Manage player scores and Tie breaker ==

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

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

Examples:
<pre>

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

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

</pre>

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

'''Tie breaker'''

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

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

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

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

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

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

== Reflexion time ==

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

== Managing errors and exceptions ==

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

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

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

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

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

== Zombie mode ==

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

While developing your zombie mode, keep in mind that:
* Do not refer to the rules, because this situation is not planned by the rules.
* Try to figure that you are playing with your friends and one of them has to leave: how can we finish the game without killing the spirit of the game?
* The idea is NOT to develop an artificial intelligence for the game.

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

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

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

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

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

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

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

== Player elimination ==

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

This case should be rare. Please don't use player elimination feature if some player just has to wait the last 10% of the game for game end. This feature is

Gamehelphex

2013-12-11T10:52:01Z

Sourisdudesert:

===INTRODUCTION===
The Hex game is a connection game independently invented by two mathematicians, Piet Hein and John Nash, respectively in 1942 and 1947. The interest of the game mainly lies on the contrast between the simplicity of its rules and the potential complexity of its strategy. Another interesting aspect is that the game can't end in a tie.

===GOAL===
The goal for each player is to create a connected path of his tokens linking his two opposite sides of the board (of his color).

===OPENING===
The first player places a first token on any cell of the board. The second player has then the choice between:
*continue playing his current color (and thus place a second token anywhere on the board);
*or decide to switch colors and keep the first move for him. In this case the first player places another token with his new color.

===TURNS===
After the first two moves (see OPENING), each player plays a token of his color on his turn. A token can be placed on any free cell of the board.

===GAME ENDS===
The game ends when one of the players has built a complete path with his tokens between his two sides of the board. The game can't end in a tie.

===VARIANTS===
The game can be played on several different board sizes. The 6x6 board is designed to help beginners to understand the basic rules and discover simple game patterns. The 11x11 board is a more classic size. The 14x14 board is the one recommended by John Nash, one of the game inventor, and the 15x15 allowed longer plays.

Gamehelphex

2013-12-11T10:51:12Z

Sourisdudesert: Reverted edits by Trociu (talk) to last revision by Kennyyy

===INTRODUCTION===
Le jeu de Hex est un jeu de placement inventé indépendamment par deux mathématiciens, Piet Hein et John Nash, respectivement en 1942 et 1947. L’intérêt principal du jeu tiens a l'opposition entre la simplicité des règles et la complexité des stratégies mises en jeu. Qui plus est, le jeu ne peut finir en match nul, ce qui lui confère un autre aspect intéressant.

===OBJECTIF===
Pour chacun des joueurs le but du jeu est de créer une ligne de pions de sa couleur reliant ses deux cotes du plateau (de sa propre couleur également).

===OUVERTURE===
Le premier joueur joue un premier pion sur n'importe quelle case du plateau. Le second joueur a alors le choix entre:
*continuer a jouer avec sa couleur sur n'importe quelle autre case du plateau;
*ou décider d’échanger sa couleur avec son adversaire et de prendre le premier pion placé pour lui. Dans ce cas le premier joueur prend le prochain tour.

===TOURS===
Apres les deux premiers tours (voir OUVERTURE), chaque joueur joue un pion de sa couleur a son tour. Un pion peut-être placé sur n'importe quelle case libre du plateau.

===FIN===
Le jeu s’arrête lorsqu'un des joueur a créé une ligne continue antre ses deux cotes du plateau. Il ne peut y avoir d’égalité ou de jeu nul.

===VARIANTES===
Le jeu peut se jouer sur différentes tailles de plateau. Le 6x6 est a réserver aux débutant et permet d'apprendre facilement les règles et de repérer les premiers "motifs" de jeu. Le 11x11 est une taille classiquement jouée. Le 14x14 est la taille recommandée par John Nash, un des inventeur du jeu, tandis que le 15x15 permet des parties plus longues et potentiellement plus stratégiques.

Contact us

2013-11-27T21:59:46Z

Sourisdudesert:

Game art: img directory

2013-10-20T20:23:41Z

Sourisdudesert: /* Requested images */

== Requested images ==

The following images are requested by BGA:

;game_box.png
* It is displayed on the main site on the game description page and when creating a table (280x280 px).
* It should be a 3D image of a physical copy of the game box as it appears in an online shop.
* It is better to take the version of the game that is coherent with the game art used in the adaptation, and from the original publisher of the game.
* The background of the image must be transparent.
* If you don't have a 3D version of the game box, you can use the following website to create one: http://www.3d-pack.com/

;game_icon.png

* It is the icon displayed in the lists of games and tables (50x50 px).
* This one should not be transparent, and shouldn't have a border (a black border will be add by BGA).
* The objective of this icon is to make the game recognizable among the other games. A good idea is to take a part of the game cover that is distinctive (ex: the game title).

;publisher.png
* It is the logo of the publisher of the game, displayed on the game description page.
* The width must be 150 px. The height can be anything. The image could be transparent.

;publisher2.png (optional)
* If the game has been co-published by 2 publishers, you should upload a second image named "publisher2.png" (same characteristic than the first one).

'''Important''': when you modify these images, you MUST click on "Reload game box image" from the Control Panel in order your update can be taken into account.

== Game art ==

You must upload in img directory all images of your game interface.

=== Images loading ===

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

Note that you can tune the way images are loaded with Javascript method "dontPreloadImage" (see [[Game_interface_logic:_yourgamename.js|Game Interface Logic]]).

=== Images format ===

You can use 3 image format while building your game interface:
;jpg images

should be used for non-transparent images. Jpg are usually lighter than Pngs, so please choose Jpg for big pictures (ex: game board, cards) when you don't need transparency to accelerate game load.

;png images

should be used for transparent images.

;gif images

can be used for animated images. This is not recommended to use gif animated images as they can upset players, but for some specific interface element this could be useful.

=== Use CSS Sprites ===

To limit the number of images load and make the game load faster, you must use CSS sprites, ie you must gather several images in a single one.

To learn more on CSS Sprites:
* [http://www.w3schools.com/css/css_image_sprites.asp CSS sprites (W3C documentation)].
* [[Game interface stylesheet: yourgamename.css]]

Studio back-office

2013-10-16T08:54:43Z

Sourisdudesert:

'''IMPORTANT''': the Studio back-office is now '''DEPRECATED'''. Most of its functionalities are now accessible from "Control Panel / Manage Games / Your games".

You will find the URL to the Studio back-office in the 'resources.html' file at the root of your SFTP access.

Here is a list and description of the links and functions in this back-office.

Click on a menu to display its content.

=== Documentation ===

Contains links to this wiki, the development forum and the bugs forum.

=== Database ===

Contains a link to the Studio database administration tool (PHPMyAdmin).

Your login / password for this tool is the same as for your SFTP access.

('''DEPRECATED''': now you can access to your game database with the link "Game Database" at the bottom of your game page).

=== Sources ===

Contains a form for committing your sources to the BGA repository.
* Game name field should contain the name of your game (lower case, no space). Ex: puertorico
* Comment field should contain your commit comment describing changes to the code since your last commit.

You should commit from time to time when you hit some landmarks in your development. This is an extra assurance not to lose your code, and to have the possibility (by asking BGA administrators) to get a previous version of your code if you need to backtrack.

('''DEPRECATED''': now this function is available from your Control Panel).

=== Logs ===

Gives you a web based access to the studio server logs.

; Current table error log
: main log of interest to you while developing, it contains the error happening at the table you are currently playing at.
('''DEPRECATED''': now you can access this log with the coreesponding link at the bottom of your game page).
; Current table request logs
: this log traces all the actions happening at the table you are currently playing at.
('''DEPRECATED''': now you can access this log with the coreesponding link at the bottom of your game page).
; Javascript error log
: this log traces all the Javascript errors happening on the client side. Errors are also briefly displayed in your browser, but in this log it's better formatted and you can look a it quietly.
('''DEPRECATED''': you should use your Javascript console / Firebug plugin to do this).
; Gameserver error log
: this log traces all errors happening on the gameserver. It should mainly be useful if your game setup crashes (ie before your table is ready, so before errors are collected in the current table error log), for example if there is a syntax error in your 'dbmodel.sql' file.
('''DEPRECATED''': errors during the game setup appears now directly in a red error message during your "Express start").
; HTTP error log
: this log traces the web server errors. This is useful to look at PHP syntax errors and warnings.
('''DEPRECATED''': errors now appear directly in a red message during the game).

Please note that the three last logs are common to all games being developed on the platform, so there may be some noise in the data you are interested in.

You can open the log links in a different tab and just hit F5 when you need to refresh. The URL you will get for the new tab has a "?n=100" parameter that gives the number of lines to display: you can modify it in the URL if you need more.

Game meta-information: gameinfos.inc.php

2013-10-07T16:25:29Z

Sourisdudesert:

From this file, you can edit the various meta-information of your game.

Once you modified the file, don't forget to click on "Reload game informations" from the Control Panel in order in can be taken into account.

Most information provided in this file are self-explainable. Some information, though:

* You are not allowed to set the "'''is_beta'''" to 0 before the game has been released on BGA and stabilized.

* "'''fast/medium/slow_additional_time'''": please set high values here: after the game has been released, we will lower these value to match the real game duration.

* "'''players'''": during the first step of development of a game, you'd better allow the "1 player" configuration: much easy to start/stop a game this way.

* '''suggest_player_number''' / '''not_recommend_player_number''': don't specify anything here if there is no configuration that is REALLY better/worst than another one. You can check player's poll on BoardGameGeek game page if you have any doubt.

== Tags ==

Any number of '''Tags''' can be attribute to your game. Tags are useful to place your game in the correct place and to give a good quick overview of what the game is about to players.

Main game category (you MUST specify one tag AND ONLY ONE from this category):
* 1: Abstract game
* 2: Casual games
* 3: For regular players
* 4: For core gamers

Other tags (you can specify any numbers of tags):
* 10: Short game (<10 minutes)
* 11: Medium length game (10 minutes to 30 minutes)
* 12: Long game (>30mn)
* 20: Awarded game (Win a prestigious award) (the game must have been at the '''first''' place of one the [http://boardgamegeek.com/wiki/page/Gaming_Industry_Awards# following major awards list]).
* 22: Prototype (This game has not been published yet)
* 23: Classic (This game is a classic from Public Domain)
* 30: 2 players (2p game / best with 2 players)
* 100: Fantasy theme
* 101: Science Fiction them
* 102: Historical theme
* 103: Adventure
* 104: Exploration
* 105: Conquest
* 106: Building
* 200: Card game (Cards plays a central role in this game)
* 201: Dice
* 202: Solo game
* 203: Worker placement
* 204: Hand management
* 205: Bluff
* 206: Tile placement
* 207: Combinations
* 208: Majority
* 209: Race
* 210: Collection

BGA Game licenses

2013-09-30T19:57:56Z

Sourisdudesert:

== What is a "licence" ==

Almost all games on Board Game Arena platform are adaptations of existing commercial "real" board games. To propose an adaption of one of this board game on a website, the right owners must grant a licence/authorization to this website.

== Are all games on BGA licenced by their respective right owners? ==

Yes.

== Where can I find available games licences ==

http://en.studio.boardgamearena.com/#!page/availablelicences

== What if I start developing a game that is not on the "Available licences"? ==

We allow developers to start any project on the Studio. But when your project is going to be live on BGA, it will be rejected during the review process.

Exception: games on the public domain are of course not concerned.

== Wow, I WANT to develop a game on this list! ==

Cool :)

But before creating a new project please takes some seconds to check if someone is not already developing this game. If this is the case, maybe you can propose to join the project?

[http://en.studio.boardgamearena.com/#!projects Check the list of current projects]

== What has to be done to add a game on this list? ==

The right owners has to give an licence/authorization to BGA.

Publishers do not have to pay anything to BGA for this, they just have to give their "go". Most of the time, publishers wants to have a formal agreement and we signed a contract.

'''Important''': you CAN'T take the initiative to ask a licence authorization on behalf of BGA, because the authorization has to be granted to BGA (read more below).

== Why all best-sellers games I love are not on that list? ==

As you can imagine, the more popular a game is, the most difficult it is to have an agreement to host this game on BGA.

So if you think about a particular very popular game that is not on this list, the reason for this rather be "we asked and this was impossible" than "we did'nt think of this".

We are pretty lucky to have a very nice platform that convince the most prestigious publishers to host their games here, but of course we can't convince -everyone-.

== I want my prototype/unpublished game on BGA ==

This is possible, BUT most of the time, we consider this is a bad idea for the following reasons:
* if your game has not been published yet, there is certainly a good reason - most of the time there is still some more work to do on the game itself. Publishing a game on BGA that is not 100% finalized won't help you to finalize it.
* as a rule of thumb, popular board games on BGA are games that are popular in the real world. As a consequence prototypes don't have a big audience on BGA.
* we also discourage you to develop your own game: we build better games adaptation with a designer that focus on the gameplay and a developer that focus on the realization.

So basically you can develop your prototype/unpublished game on BGA, but we encourage you to do it only if you are in one/several of the situation below:
* the game is going to be published in the near future.
* the game design process is really 100% done: the game is ready to be published in its current shape (ex: self-publishing game, game in a crowdfunding process...).
* you want to test a game with a big number of players to finalize some minor things ("balance").

== What if I really want to develop a particular game that is NOT on the list below? ==

This is the most asked question, to please follow the instructions:

=== 0: ===

In any case: please, do not contact publishers without asking us before. Please imagine you are a game publisher who just published a popular game: what would you do if you received 40 emails from 40 developers speaking about "BGA platform" and wanting to build an adaptation on it?

Continue to 1.

=== 1: ===

At first, you should determine who is the owner of the electronic rights of a game. Most of the time, this is the original publisher of the game. The original publisher is not always easy to find, because in general board games are translated&published in each countries by a local publisher.

To find the original publisher:
* check in which country the game has been published first (ex: If it's in Poland, the original publisher is probably polish).
* check the copyright notice at the end of the rules, where the original publisher is mentioned almost all the time.
* very often, if two publishers are mentioned on a gamebox, the well-known publisher is the publisher from your country and the other one is the original publisher.

Particular case: if the game is themed with a prestigious licence (Star Wars, Lord of the Ring, some TV show, some well known novel...), you can stop here immediately: contracts between game publishers and prestigious licences owners are very restrictive, and there is 99% chance that an online adaptation on BGA is not welcome.

Continue to 2

=== 2: ===

Read the publisher list from the "available licence" page to check if BGA already work with this publisher.

If YES, continue to 3.
If NO, continue to 4.

However, if the publisher is listed as "not working with BGA", you can stop here immediately. It happens sometimes that some publishers are not convinced by online boardgaming and this is their right to think this. BGA team regularly meet new publishers during board games events to show them the platform, so we're working on this but -again- we cannot convince everyone.

=== 3: ===

Is there already a game licenced by this publisher that has to be developed?

If YES: as a rule of thumb, we do not ask more than one game to a publisher at a time. When we ask a licence for a game, a publisher expect that the game will be developed and published online. So we develop and publish a game before asking for another.
If you really want to develop a game from this particular publisher, the best option for you is to help to develop the game that is currently licenced and then to ask us to request the game you'd like to develop.

If NO: just ask us which game you want to develop and we would be happy to ask the publisher the authorization!

=== 4: ===

We never worked with this publisher before.

If you have already developed a game on BGA, we would be happy to ask the publisher the authorization :)

If this is your first game on BGA, we probably advise you to start with a game already on the list. Why? Because unfortunately, some developers are asking us to request a licence, and don't finish the development afterwards. When we ask for a licence, we are more comfortable if you already show that you are able to realize an adaptation.

Particular case: if you already know the publisher PERSONALLY, or have some contact there, please tell us so we can help you to setup a contract to host a game adaptation on BGA.

BGA Game licenses

2013-09-30T19:56:30Z

Sourisdudesert: /* 2: */

== What is a "licence" ==

Almost all games on Board Game Arena platform are adaptations of existing commercial "real" board games. To propose an adaption of one of this board game on a website, the right owners must grant a licence/authorization to this website.

== Are all games on BGA licenced by their respective right owners? ==

Yes.

== What if I start developing a game that is not on the "Available licences"? ==

We allow developers to start any project on the Studio. But when your project is going to be live on BGA, it will be rejected during the review process.

Exception: games on the public domain are of course not concerned.

== Wow, I WANT to develop a game on this list! ==

Cool :)

But before creating a new project please takes some seconds to check if someone is not already developing this game. If this is the case, maybe you can propose to join the project?

[http://en.studio.boardgamearena.com/#!projects Check the list of current projects]

== What has to be done to add a game on this list? ==

The right owners has to give an licence/authorization to BGA.

Publishers do not have to pay anything to BGA for this, they just have to give their "go". Most of the time, publishers wants to have a formal agreement and we signed a contract.

'''Important''': you CAN'T take the initiative to ask a licence authorization on behalf of BGA, because the authorization has to be granted to BGA (read more below).

== Why all best-sellers games I love are not on that list? ==

As you can imagine, the more popular a game is, the most difficult it is to have an agreement to host this game on BGA.

So if you think about a particular very popular game that is not on this list, the reason for this rather be "we asked and this was impossible" than "we did'nt think of this".

We are pretty lucky to have a very nice platform that convince the most prestigious publishers to host their games here, but of course we can't convince -everyone-.

== I want my prototype/unpublished game on BGA ==

This is possible, BUT most of the time, we consider this is a bad idea for the following reasons:
* if your game has not been published yet, there is certainly a good reason - most of the time there is still some more work to do on the game itself. Publishing a game on BGA that is not 100% finalized won't help you to finalize it.
* as a rule of thumb, popular board games on BGA are games that are popular in the real world. As a consequence prototypes don't have a big audience on BGA.
* we also discourage you to develop your own game: we build better games adaptation with a designer that focus on the gameplay and a developer that focus on the realization.

So basically you can develop your prototype/unpublished game on BGA, but we encourage you to do it only if you are in one/several of the situation below:
* the game is going to be published in the near future.
* the game design process is really 100% done: the game is ready to be published in its current shape (ex: self-publishing game, game in a crowdfunding process...).
* you want to test a game with a big number of players to finalize some minor things ("balance").

== What if I really want to develop a particular game that is NOT on the list below? ==

This is the most asked question, to please follow the instructions:

=== 0: ===

In any case: please, do not contact publishers without asking us before. Please imagine you are a game publisher who just published a popular game: what would you do if you received 40 emails from 40 developers speaking about "BGA platform" and wanting to build an adaptation on it?

Continue to 1.

=== 1: ===

At first, you should determine who is the owner of the electronic rights of a game. Most of the time, this is the original publisher of the game. The original publisher is not always easy to find, because in general board games are translated&published in each countries by a local publisher.

To find the original publisher:
* check in which country the game has been published first (ex: If it's in Poland, the original publisher is probably polish).
* check the copyright notice at the end of the rules, where the original publisher is mentioned almost all the time.
* very often, if two publishers are mentioned on a gamebox, the well-known publisher is the publisher from your country and the other one is the original publisher.

Particular case: if the game is themed with a prestigious licence (Star Wars, Lord of the Ring, some TV show, some well known novel...), you can stop here immediately: contracts between game publishers and prestigious licences owners are very restrictive, and there is 99% chance that an online adaptation on BGA is not welcome.

Continue to 2

=== 2: ===

Read the publisher list from the "available licence" page to check if BGA already work with this publisher.

If YES, continue to 3.
If NO, continue to 4.

However, if the publisher is listed as "not working with BGA", you can stop here immediately. It happens sometimes that some publishers are not convinced by online boardgaming and this is their right to think this. BGA team regularly meet new publishers during board games events to show them the platform, so we're working on this but -again- we cannot convince everyone.

=== 3: ===

Is there already a game licenced by this publisher that has to be developed?

If YES: as a rule of thumb, we do not ask more than one game to a publisher at a time. When we ask a licence for a game, a publisher expect that the game will be developed and published online. So we develop and publish a game before asking for another.
If you really want to develop a game from this particular publisher, the best option for you is to help to develop the game that is currently licenced and then to ask us to request the game you'd like to develop.

If NO: just ask us which game you want to develop and we would be happy to ask the publisher the authorization!

=== 4: ===

We never worked with this publisher before.

If you have already developed a game on BGA, we would be happy to ask the publisher the authorization :)

If this is your first game on BGA, we probably advise you to start with a game already on the list. Why? Because unfortunately, some developers are asking us to request a licence, and don't finish the development afterwards. When we ask for a licence, we are more comfortable if you already show that you are able to realize an adaptation.

Particular case: if you already know the publisher PERSONALLY, or have some contact there, please tell us so we can help you to setup a contract to host a game adaptation on BGA.

BGA Game licenses

2013-09-30T19:55:45Z

Sourisdudesert: /* 1: */

== What is a "licence" ==

Almost all games on Board Game Arena platform are adaptations of existing commercial "real" board games. To propose an adaption of one of this board game on a website, the right owners must grant a licence/authorization to this website.

== Are all games on BGA licenced by their respective right owners? ==

Yes.

== What if I start developing a game that is not on the "Available licences"? ==

We allow developers to start any project on the Studio. But when your project is going to be live on BGA, it will be rejected during the review process.

Exception: games on the public domain are of course not concerned.

== Wow, I WANT to develop a game on this list! ==

Cool :)

But before creating a new project please takes some seconds to check if someone is not already developing this game. If this is the case, maybe you can propose to join the project?

[http://en.studio.boardgamearena.com/#!projects Check the list of current projects]

== What has to be done to add a game on this list? ==

The right owners has to give an licence/authorization to BGA.

Publishers do not have to pay anything to BGA for this, they just have to give their "go". Most of the time, publishers wants to have a formal agreement and we signed a contract.

'''Important''': you CAN'T take the initiative to ask a licence authorization on behalf of BGA, because the authorization has to be granted to BGA (read more below).

== Why all best-sellers games I love are not on that list? ==

As you can imagine, the more popular a game is, the most difficult it is to have an agreement to host this game on BGA.

So if you think about a particular very popular game that is not on this list, the reason for this rather be "we asked and this was impossible" than "we did'nt think of this".

We are pretty lucky to have a very nice platform that convince the most prestigious publishers to host their games here, but of course we can't convince -everyone-.

== I want my prototype/unpublished game on BGA ==

This is possible, BUT most of the time, we consider this is a bad idea for the following reasons:
* if your game has not been published yet, there is certainly a good reason - most of the time there is still some more work to do on the game itself. Publishing a game on BGA that is not 100% finalized won't help you to finalize it.
* as a rule of thumb, popular board games on BGA are games that are popular in the real world. As a consequence prototypes don't have a big audience on BGA.
* we also discourage you to develop your own game: we build better games adaptation with a designer that focus on the gameplay and a developer that focus on the realization.

So basically you can develop your prototype/unpublished game on BGA, but we encourage you to do it only if you are in one/several of the situation below:
* the game is going to be published in the near future.
* the game design process is really 100% done: the game is ready to be published in its current shape (ex: self-publishing game, game in a crowdfunding process...).
* you want to test a game with a big number of players to finalize some minor things ("balance").

== What if I really want to develop a particular game that is NOT on the list below? ==

This is the most asked question, to please follow the instructions:

=== 0: ===

In any case: please, do not contact publishers without asking us before. Please imagine you are a game publisher who just published a popular game: what would you do if you received 40 emails from 40 developers speaking about "BGA platform" and wanting to build an adaptation on it?

Continue to 1.

=== 1: ===

At first, you should determine who is the owner of the electronic rights of a game. Most of the time, this is the original publisher of the game. The original publisher is not always easy to find, because in general board games are translated&published in each countries by a local publisher.

To find the original publisher:
* check in which country the game has been published first (ex: If it's in Poland, the original publisher is probably polish).
* check the copyright notice at the end of the rules, where the original publisher is mentioned almost all the time.
* very often, if two publishers are mentioned on a gamebox, the well-known publisher is the publisher from your country and the other one is the original publisher.

Particular case: if the game is themed with a prestigious licence (Star Wars, Lord of the Ring, some TV show, some well known novel...), you can stop here immediately: contracts between game publishers and prestigious licences owners are very restrictive, and there is 99% chance that an online adaptation on BGA is not welcome.

Continue to 2

=== 2: ===

Read the publisher list below to check if BGA already work with this publisher.

If YES, continue to 3.
If NO, continue to 4.

However, if the publisher is listed as "not working with BGA", you can stop here immediately. It happens sometimes that some publishers are not convinced by online boardgaming and this is their right to think this. BGA team regularly meet new publishers during board games events to show them the platform, so we're working on this but -again- we cannot convince everyone.

=== 3: ===

Is there already a game licenced by this publisher that has to be developed?

If YES: as a rule of thumb, we do not ask more than one game to a publisher at a time. When we ask a licence for a game, a publisher expect that the game will be developed and published online. So we develop and publish a game before asking for another.
If you really want to develop a game from this particular publisher, the best option for you is to help to develop the game that is currently licenced and then to ask us to request the game you'd like to develop.

If NO: just ask us which game you want to develop and we would be happy to ask the publisher the authorization!

=== 4: ===

We never worked with this publisher before.

If you have already developed a game on BGA, we would be happy to ask the publisher the authorization :)

If this is your first game on BGA, we probably advise you to start with a game already on the list. Why? Because unfortunately, some developers are asking us to request a licence, and don't finish the development afterwards. When we ask for a licence, we are more comfortable if you already show that you are able to realize an adaptation.

Particular case: if you already know the publisher PERSONALLY, or have some contact there, please tell us so we can help you to setup a contract to host a game adaptation on BGA.

BGA Game licenses

2013-09-30T19:54:07Z

Sourisdudesert: /* What if I really want to develop a particular game that is NOT on the list below? */

== What is a "licence" ==

Almost all games on Board Game Arena platform are adaptations of existing commercial "real" board games. To propose an adaption of one of this board game on a website, the right owners must grant a licence/authorization to this website.

== Are all games on BGA licenced by their respective right owners? ==

Yes.

== What if I start developing a game that is not on the "Available licences"? ==

We allow developers to start any project on the Studio. But when your project is going to be live on BGA, it will be rejected during the review process.

Exception: games on the public domain are of course not concerned.

== Wow, I WANT to develop a game on this list! ==

Cool :)

But before creating a new project please takes some seconds to check if someone is not already developing this game. If this is the case, maybe you can propose to join the project?

[http://en.studio.boardgamearena.com/#!projects Check the list of current projects]

== What has to be done to add a game on this list? ==

The right owners has to give an licence/authorization to BGA.

Publishers do not have to pay anything to BGA for this, they just have to give their "go". Most of the time, publishers wants to have a formal agreement and we signed a contract.

'''Important''': you CAN'T take the initiative to ask a licence authorization on behalf of BGA, because the authorization has to be granted to BGA (read more below).

== Why all best-sellers games I love are not on that list? ==

As you can imagine, the more popular a game is, the most difficult it is to have an agreement to host this game on BGA.

So if you think about a particular very popular game that is not on this list, the reason for this rather be "we asked and this was impossible" than "we did'nt think of this".

We are pretty lucky to have a very nice platform that convince the most prestigious publishers to host their games here, but of course we can't convince -everyone-.

== I want my prototype/unpublished game on BGA ==

This is possible, BUT most of the time, we consider this is a bad idea for the following reasons:
* if your game has not been published yet, there is certainly a good reason - most of the time there is still some more work to do on the game itself. Publishing a game on BGA that is not 100% finalized won't help you to finalize it.
* as a rule of thumb, popular board games on BGA are games that are popular in the real world. As a consequence prototypes don't have a big audience on BGA.
* we also discourage you to develop your own game: we build better games adaptation with a designer that focus on the gameplay and a developer that focus on the realization.

So basically you can develop your prototype/unpublished game on BGA, but we encourage you to do it only if you are in one/several of the situation below:
* the game is going to be published in the near future.
* the game design process is really 100% done: the game is ready to be published in its current shape (ex: self-publishing game, game in a crowdfunding process...).
* you want to test a game with a big number of players to finalize some minor things ("balance").

== What if I really want to develop a particular game that is NOT on the list below? ==

This is the most asked question, to please follow the instructions:

=== 0: ===

In any case: please, do not contact publishers without asking us before. Please imagine you are a game publisher who just published a popular game: what would you do if you received 40 emails from 40 developers speaking about "BGA platform" and wanting to build an adaptation on it?

Continue to 1.

=== 1: ===

At first, you should determine who is the owner of the electronic rights of a game. Most of the time, this is the original publisher of the game. The original publisher is not always easy to find, because in general board games are translated&published in each countries by a local publisher. To find the original publisher:
_ check in which country the game has been published first (ex: If it's in Poland, the original publisher is probably polish).
_ check the copyright notice at the end of the rules, where the original publisher is mentioned almost all the time.
_ very often, if two publishers are mentioned on a gamebox, the well-known publisher is the publisher from your country and the other one is the original publisher.

Particular case: if the game is themed with a prestigious licence (Star Wars, Lord of the Ring, some TV show, some well known novel...), you can stop here immediately: contracts between game publishers and prestigious licences owners are very restrictive, and there is 99% chance that an online adaptation on BGA is not welcome.

Continue to 2

=== 2: ===

Read the publisher list below to check if BGA already work with this publisher.

If YES, continue to 3.
If NO, continue to 4.

However, if the publisher is listed as "not working with BGA", you can stop here immediately. It happens sometimes that some publishers are not convinced by online boardgaming and this is their right to think this. BGA team regularly meet new publishers during board games events to show them the platform, so we're working on this but -again- we cannot convince everyone.

=== 3: ===

Is there already a game licenced by this publisher that has to be developed?

If YES: as a rule of thumb, we do not ask more than one game to a publisher at a time. When we ask a licence for a game, a publisher expect that the game will be developed and published online. So we develop and publish a game before asking for another.
If you really want to develop a game from this particular publisher, the best option for you is to help to develop the game that is currently licenced and then to ask us to request the game you'd like to develop.

If NO: just ask us which game you want to develop and we would be happy to ask the publisher the authorization!

=== 4: ===

We never worked with this publisher before.

If you have already developed a game on BGA, we would be happy to ask the publisher the authorization :)

If this is your first game on BGA, we probably advise you to start with a game already on the list. Why? Because unfortunately, some developers are asking us to request a licence, and don't finish the development afterwards. When we ask for a licence, we are more comfortable if you already show that you are able to realize an adaptation.

Particular case: if you already know the publisher PERSONALLY, or have some contact there, please tell us so we can help you to setup a contract to host a game adaptation on BGA.