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

Gamehelppuertorico

2014-03-02T10:27:41Z

Een: /* Two players variant */

== Goal ==

Be the player with the most victory points at the end of the game by collecting:

* victory points earned for buildings
* victory point tokens earned at the captain phase
* conditional victory points earned at the end of the game for occupied large buildings

In case of a tie, the player owning the most doubloons and goods is the winner.

== Rules summary ==

The game is played over several rounds.
At the start of a round, the governor selects a role, then each player in turn selects a role.
At the end of the round, the governor token moves to the next player.

When a role has been chosen, each player in turn plays the action for this role. Only the player who selected the role can use the role privilege.

Available roles are the following:

* Mayor: colonists set foot in the new world ! Privilege : the mayor can get one more colonist from the supply. Action : in turn, begining with the mayor, players get one colonist from the ship, until it is empty. Then players have to set colonists on their buildings and plantations.
* Craftsman: goods are produced. Privilege : the craftsman can produce one more good of his choice. Action : produce goods for your occupied buildings and plantations.
* Trader: goods are sold to the trading house. Privilege : the trader earns 1 extra doubloon if he sells. Action : sell one good the trading house doesn't have yet.
* Settler : plantations settlement. Privilege : the settler can get a quarry instead of a plantation. Action : get a plantation chosen among those available.
* Builder : buildings are bought and built. Privilege : the builder can get a building for 1 doubloon less than the regular price. Action : get a building chosen among those available.
* Captain : victory points are won by shipping goods to the old world. Privilege : the captain earns one extra victory points if he ships some goods. Action : select a type of good to load on a cargo ship; 1 victory point is earned for each barrel of this type of good loaded on the ship.
* Prospector : gold rush brings money ! Privilege : the prospector gets one doubloon from the bank. Action : none.

Please also note that occupied violet buildings have modifier effects for role actions.

End of game happens at the end of the round for which one of the following events comes to pass :

* there is not enough colonists in the supply to refill the colonist ship at the end of the mayor phase
* the last victory point token has been earned during the captain phase
* at least one of the players built on his 12th and last free space in the city.

== Playing online ==

Choosing a role : click on the role of your choice in the list on the right of your game board.

* Mayor role : accept or refuse to get an extra colonist from the supply. Colonists are then automatically recruited by players. Click on a building or a plantation to setup a colonist on it. Click on a colonist to send it back to San Juan (the counter for colonists in San Juan is situated in your player panel on the right of the page).

* Craftsman role : goods production is automated (counters for goods owned are in the player panel on the right of the page). Then, choose one extra good that you can produce as your privilege.

* Trader role : choose a good that you want to sell by clicking on the appropriate counter in your player panel.

* Settler role : click on the plantation (or quarry) that you want. Placement on your board is automated.

* Builder role : click on the building that you want to buy. Placement on your board is automated.

* Captain role : click on the cargo boat on which you want to ship some goods. Then choose the type of good that you want to ship by clicking on the appropriate counter in your player panel. At the end of the captain phase, if you have some goods to store (warehouse or windrose), click on the corresponding counter. Stored goods will be highlighted by a red frame.

* Prospector role : doubloon is earned immediately.

Tooltips are available to give information on roles and buildings by hovering over game elements with the mouse.

== 'Balanced game' variant ==

This variant implements two game balance fixes giving each player an equal chance of winning as listed in the [http://en.wikipedia.org/wiki/Puerto_Rico_%28board_game%29 Puerto Rico (board game) Wikipedia page].

* The prices of the Factory and University buildings are swapped so that the Factory costs 8 doubloons and the University costs 7 doubloons
* Any player that starts with a corn plantation starts with 1 doubloon less than the players that start with an indigo plantation.

== Two players variant ==

Craftsman Angst : if this variant is selected, players alternate selecting a role as usual, until the Governor has selected '''three''' roles and the opponent has selected '''two''' roles (instead of three in a classic two players game), then the governor token goes to the opponent and a new round starts.
This variant avoids the consecutive selection of two roles by the same player which happens on a change of round with the classic two player game rules.

This variant is described on [http://www.boardgamegeek.com/thread/679955/the-craftsman-angst-variant-the-most-popular-revis Board Game Geek].

'''Have a good game !'''

Gamehelppuertorico

2014-03-02T10:26:22Z

Een:

== Goal ==

Be the player with the most victory points at the end of the game by collecting:

* victory points earned for buildings
* victory point tokens earned at the captain phase
* conditional victory points earned at the end of the game for occupied large buildings

In case of a tie, the player owning the most doubloons and goods is the winner.

== Rules summary ==

The game is played over several rounds.
At the start of a round, the governor selects a role, then each player in turn selects a role.
At the end of the round, the governor token moves to the next player.

When a role has been chosen, each player in turn plays the action for this role. Only the player who selected the role can use the role privilege.

Available roles are the following:

* Mayor: colonists set foot in the new world ! Privilege : the mayor can get one more colonist from the supply. Action : in turn, begining with the mayor, players get one colonist from the ship, until it is empty. Then players have to set colonists on their buildings and plantations.
* Craftsman: goods are produced. Privilege : the craftsman can produce one more good of his choice. Action : produce goods for your occupied buildings and plantations.
* Trader: goods are sold to the trading house. Privilege : the trader earns 1 extra doubloon if he sells. Action : sell one good the trading house doesn't have yet.
* Settler : plantations settlement. Privilege : the settler can get a quarry instead of a plantation. Action : get a plantation chosen among those available.
* Builder : buildings are bought and built. Privilege : the builder can get a building for 1 doubloon less than the regular price. Action : get a building chosen among those available.
* Captain : victory points are won by shipping goods to the old world. Privilege : the captain earns one extra victory points if he ships some goods. Action : select a type of good to load on a cargo ship; 1 victory point is earned for each barrel of this type of good loaded on the ship.
* Prospector : gold rush brings money ! Privilege : the prospector gets one doubloon from the bank. Action : none.

Please also note that occupied violet buildings have modifier effects for role actions.

End of game happens at the end of the round for which one of the following events comes to pass :

* there is not enough colonists in the supply to refill the colonist ship at the end of the mayor phase
* the last victory point token has been earned during the captain phase
* at least one of the players built on his 12th and last free space in the city.

== Playing online ==

Choosing a role : click on the role of your choice in the list on the right of your game board.

* Mayor role : accept or refuse to get an extra colonist from the supply. Colonists are then automatically recruited by players. Click on a building or a plantation to setup a colonist on it. Click on a colonist to send it back to San Juan (the counter for colonists in San Juan is situated in your player panel on the right of the page).

* Craftsman role : goods production is automated (counters for goods owned are in the player panel on the right of the page). Then, choose one extra good that you can produce as your privilege.

* Trader role : choose a good that you want to sell by clicking on the appropriate counter in your player panel.

* Settler role : click on the plantation (or quarry) that you want. Placement on your board is automated.

* Builder role : click on the building that you want to buy. Placement on your board is automated.

* Captain role : click on the cargo boat on which you want to ship some goods. Then choose the type of good that you want to ship by clicking on the appropriate counter in your player panel. At the end of the captain phase, if you have some goods to store (warehouse or windrose), click on the corresponding counter. Stored goods will be highlighted by a red frame.

* Prospector role : doubloon is earned immediately.

Tooltips are available to give information on roles and buildings by hovering over game elements with the mouse.

== 'Balanced game' variant ==

This variant implements two game balance fixes giving each player an equal chance of winning as listed in the [http://en.wikipedia.org/wiki/Puerto_Rico_%28board_game%29 Puerto Rico (board game) Wikipedia page].

* The prices of the Factory and University buildings are swapped so that the Factory costs 8 doubloons and the University costs 7 doubloons
* Any player that starts with a corn plantation starts with 1 doubloon less than the players that start with an indigo plantation.

== Two players variant ==

Craftsman Angst : if this variant is selected, players alternate selecting a role as usual, until the Governor has selected three roles and the opponent has selected two (instead of three in a classic two players game), then the governor token goes to the opponent and a new round starts.
So it avoids the consecutive selection of two roles by the same player that happens on a change of round with the classic two player game.

This variant is described on [http://www.boardgamegeek.com/thread/679955/the-craftsman-angst-variant-the-most-popular-revis Board Game Geek].

'''Have a good game !'''

Stock

2014-02-24T18:33:09Z

Een:

"Stock" is a javascript component that you can use on your game interface to display a set of elements of the same size that need to be arranged in one or several lines.

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

Stock is used for example:
* To display set of cards, typically hands (ex: in Hearts, Seasons, The Boss, Race for the Galaxy, ...).
* To display items in player panels (ex: Takenoko, Amyitis, ...)
* ... in many other situations. For example, black dice and cubes on cards in Troyes are displayed with stock components.

Using stock:
* Your items are arranged nicely and sorted by type.
* When adding (or removing) items to the set. All items slide smoothly to their new position in the set to host the new one.
* Select/unselect items is a built-in functionnality.
* You don't have to care about inserting/removing HTML piece of code: the entire life of the stock is managed by the component.

== Using stock: a simple example ==

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

At first, don't forget to add "ebg/stock" as a dependency:
<pre>
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/stock" /// <==== HERE
],
</pre>

The stock is initialized in Javascript "setup" method like this:
<pre>
// Player hand
this.playerHand = new ebg.stock();
this.playerHand.create( this, $('myhand'), this.cardwidth, this.cardheight );
</pre>

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

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

Here's how we tell stock what are the items type to display:
<pre>
// Explain there are 13 images per row in the CSS sprite image
this.playerHand.image_items_per_row = 13;

// Create cards types:
for( var color=1;color<=4;color++ )
{
for( var value=2;value<=14;value++ )
{
// Build card type id
var card_type_id = this.getCardUniqueId( color, value );
this.playerHand.addItemType( card_type_id, card_type_id, g_gamethemeurl+'img/cards.jpg', card_type_id );
}
}
</pre>

Explanations:
* At first, we tell the stock component that our CSS sprite contains 13 items per row. This way, it can find the correct image for each card type id.
* Then for the 4x13 cards, we call "addItemType" method that create the type. The arguments are the type id, the weight of the card (for sorting purpose), the URL of our CSS sprite, and the position of our card image in the CSS sprite.

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

From now, if we need to add - for example - the 5 of Heart to player's hand, we can do this.
this.playerHand.addToStock( this.getCardUniqueId( 2 /* 2=hearts */, 5 ) );

In reality, cards have some IDs, which are useful to manipulate them. This is the reason we are using "addToStockWithId" instead:
this.playerHand.addToStock( this.getCardUniqueId( 2 /* 2=hearts */, 5 ), my_card_id );

If afterwards we want to remove this card from the stock:
this.playerHand.removeFromStockById( my_card_id );

== Complete stock component reference ==

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

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

(See "Hearts" example above).

'''count():'''

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

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

Define a new type of item to the stock.

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

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

Be careful: you must specify the image url as this:
<pre>
g_gamethemeurl+'img/yourimage.png'
</pre>
* image_position: if "image" specify the URL of a CSS sprite, you must specify the position of the item image in this CSS sprite. For example, if you have a CSS sprite with 3 cubes with a size of 20x20 pixels each (so your CSS image has for example a size of 20x60 or 60x20), you specify "0" for the first cube image, 1 for the second, 2 for the third.
Important: there are more than one line of items in your CSS sprite, you must specify how many items per line you have in your CSS sprite like this:
<pre>
// Specify that there is 10 image items per row in images used in "myStockObject" control.
this.myStockObject.image_items_per_row = 10;
</pre>

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

Add an item to the stock, with the specified type.

To make your life easy, in most of the case we suggest you to use "addToStockWithId" in order to give an ID to the item added. "addToStock" is perfect when you are using a stock controls with items that are generic game material that does not need to be addressed individually (ex: a bunch of money tokens).

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

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

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

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

This is exactly the same method than "addToStock", except that you associate an ID to the newly created item.

This is especially useful:
* When you need to know which item(s) has been selected by the user (see "getSelectedItems").
* When you need to remove a specific item from the stock with "removeFromStockById"

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

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

Remove an item of the specific type from the stock.

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

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

Remove an item with a specific ID from the stock.

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

'''removeAll()'''

Remove all items from the stock.

'''getPresentTypeList()'''

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

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

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

'''resetItemsPosition()'''

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

'''item_margin'''

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

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

'''changeItemsWeight( newWeights )'''

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

Items are immediately re-sorted with the new weight.

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

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

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

'''setSelectionMode( mode )'''

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

'''setSelectionAppeareance( type )'''

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

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

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

NB: the 'class' highlighting type has not yet been deployed on the studio - 24/02/2014. This warning will be removed after the next upgrade.

'''isSelected( id )'''

Return true/false wether the specified item id has been selected or not.

'''selectItem( id )'''

Select the specified item.

'''unselectItem( id )'''

Unselect the specified item.

'''unselectAll()'''

Unselect all items of the stock.

'''onChangeSelection'''

This callback method is called when the player select/unselect an item of the stock.

You can connect this to one of your method like this:
<pre>
dojo.connect( this.myStockControl, 'onChangeSelection', this, 'onMyMethodToCall' );

(...)

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

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

Note: The "control_name" argument is the ID (the "DOM" id) of the "div" container of your stock control. Using "control_name", you can use the same callback method for different Stock control and see which one trigger the method.

'''getSelectedItems()'''

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

'''getUnselectedItems()'''

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

'''getAllItems()'''

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

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

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

By default, horizontal_overlap and vertical_overlap are 0.

When horizontal_overlap=20, it means that a stock item must overlap on 20% of the width of the previous item. horizontal_overlap can't be over 100.

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

See "Jaipur" game to see an example to use of this function.

'''onItemCreate'''

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

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

(...)

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

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

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

</pre>

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

The usual way is the following:

'''Situation A''':

When you add a card to a stock item, and this card is '''not''' coming from another stock: use "addToStockWithId" with a "from" argument set to the element of your interface where card should come from.

'''Situation B''':

When you add a card to a stock item, and this card is coming from another stock:
* on the destination Stock, use "addToStockWithId" with a "from" equals to the HTML id of the corresponding item in the source Stock. For example, If the source stock id is "myHand", then the HTML id of card 48 is "myHand_item_48".
* then, remove the source item with "removeFromStockById".
(note that it's important to do things in this order, because source item must still exists when you use it as the origin of the slide).

'''Situation C''':

When you move a card from a stock item to something that is not a stock item:
* insert the card as a classic HTML template (dojo.place / this.format_block).
* place it on the Stock item with "this.placeOnObject", using Stock item HTML id (see above).
* slide it to its new position with "this.slideToObject"
* remove the card from the Stock item with "removeFromStockById".

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

Stock

2014-02-24T18:22:08Z

Een:

"Stock" is a javascript component that you can use on your game interface to display a set of elements of the same size that need to be arranged in one or several lines.

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

Stock is used for example:
* To display set of cards, typically hands (ex: in Hearts, Seasons, The Boss, Race for the Galaxy, ...).
* To display items in player panels (ex: Takenoko, Amyitis, ...)
* ... in many other situations. For example, black dice and cubes on cards in Troyes are displayed with stock components.

Using stock:
* Your items are arranged nicely and sorted by type.
* When adding (or removing) items to the set. All items slide smoothly to their new position in the set to host the new one.
* Select/unselect items is a built-in functionnality.
* You don't have to care about inserting/removing HTML piece of code: the entire life of the stock is managed by the component.

== Using stock: a simple example ==

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

At first, don't forget to add "ebg/stock" as a dependency:
<pre>
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/stock" /// <==== HERE
],
</pre>

The stock is initialized in Javascript "setup" method like this:
<pre>
// Player hand
this.playerHand = new ebg.stock();
this.playerHand.create( this, $('myhand'), this.cardwidth, this.cardheight );
</pre>

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

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

Here's how we tell stock what are the items type to display:
<pre>
// Explain there are 13 images per row in the CSS sprite image
this.playerHand.image_items_per_row = 13;

// Create cards types:
for( var color=1;color<=4;color++ )
{
for( var value=2;value<=14;value++ )
{
// Build card type id
var card_type_id = this.getCardUniqueId( color, value );
this.playerHand.addItemType( card_type_id, card_type_id, g_gamethemeurl+'img/cards.jpg', card_type_id );
}
}
</pre>

Explanations:
* At first, we tell the stock component that our CSS sprite contains 13 items per row. This way, it can find the correct image for each card type id.
* Then for the 4x13 cards, we call "addItemType" method that create the type. The arguments are the type id, the weight of the card (for sorting purpose), the URL of our CSS sprite, and the position of our card image in the CSS sprite.

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

From now, if we need to add - for example - the 5 of Heart to player's hand, we can do this.
this.playerHand.addToStock( this.getCardUniqueId( 2 /* 2=hearts */, 5 ) );

In reality, cards have some IDs, which are useful to manipulate them. This is the reason we are using "addToStockWithId" instead:
this.playerHand.addToStock( this.getCardUniqueId( 2 /* 2=hearts */, 5 ), my_card_id );

If afterwards we want to remove this card from the stock:
this.playerHand.removeFromStockById( my_card_id );

== Complete stock component reference ==

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

With create, you create a new stock component.
Parameters:
* page: the container page. Usually: "this".
* container_div: the container "<div>" element (a void <div> element in your template, with an id).
* a stock item width and height, in pixels.

(See "Hearts" example above).

'''count():'''

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

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

Define a new type of item to the stock.

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

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

Be careful: you must specify the image url as this:
<pre>
g_gamethemeurl+'img/yourimage.png'
</pre>
* image_position: if "image" specify the URL of a CSS sprite, you must specify the position of the item image in this CSS sprite. For example, if you have a CSS sprite with 3 cubes with a size of 20x20 pixels each (so your CSS image has for example a size of 20x60 or 60x20), you specify "0" for the first cube image, 1 for the second, 2 for the third.
Important: there are more than one line of items in your CSS sprite, you must specify how many items per line you have in your CSS sprite like this:
<pre>
// Specify that there is 10 image items per row in images used in "myStockObject" control.
this.myStockObject.image_items_per_row = 10;
</pre>

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

Add an item to the stock, with the specified type.

To make your life easy, in most of the case we suggest you to use "addToStockWithId" in order to give an ID to the item added. "addToStock" is perfect when you are using a stock controls with items that are generic game material that does not need to be addressed individually (ex: a bunch of money tokens).

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

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

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

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

This is exactly the same method than "addToStock", except that you associate an ID to the newly created item.

This is especially useful:
* When you need to know which item(s) has been selected by the user (see "getSelectedItems").
* When you need to remove a specific item from the stock with "removeFromStockById"

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

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

Remove an item of the specific type from the stock.

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

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

Remove an item with a specific ID from the stock.

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

'''removeAll()'''

Remove all items from the stock.

'''getPresentTypeList()'''

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

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

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

'''resetItemsPosition()'''

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

'''item_margin'''

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

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

'''changeItemsWeight( newWeights )'''

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

Items are immediately re-sorted with the new weight.

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

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

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

'''setSelectionMode( mode )'''

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

'''setSelectionAppeareance( type )'''

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

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

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

NB: the 'class' highlighting type has not yet been deployed on the studio - 24/02/2014. This warning will be removed after the next upgrade.

'''isSelected( id )'''

Return true/false wether the specified item id has been selected or not.

'''selectItem( id )'''

Select the specified item.

'''unselectItem( id )'''

Unselect the specified item.

'''unselectAll()'''

Unselect all items of the stock.

'''onChangeSelection'''

This callback method is called when the player select/unselect an item of the stock.

You can connect this to one of your method like this:
<pre>
dojo.connect( this.myStockControl, 'onChangeSelection', this, 'onMyMethodToCall' );

(...)

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

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

Note: The "control_name" argument is the ID (the "DOM" id) of the <div> container of your stock control. Using "control_name", you can use the same callback method for different Stock control and see which one trigger the method.

'''getSelectedItems()'''

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

'''getUnselectedItems()'''

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

'''getAllItems()'''

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

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

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

By default, horizontal_overlap and vertical_overlap are 0.

When horizontal_overlap=20, it means that a stock item must overlap on 20% of the width of the previous item. horizontal_overlap can't be over 100.

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

See "Jaipur" game to see an example to use of this function.

'''onItemCreate'''

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

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

(...)

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

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

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

</pre>

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

The usual way is the following:

'''Situation A''':

When you add a card to a stock item, and this card is '''not''' coming from another stock: use "addToStockWithId" with a "from" argument set to the element of your interface where card should come from.

'''Situation B''':

When you add a card to a stock item, and this card is coming from another stock:
* on the destination Stock, use "addToStockWithId" with a "from" equals to the HTML id of the corresponding item in the source Stock. For example, If the source stock id is "myHand", then the HTML id of card 48 is "myHand_item_48".
* then, remove the source item with "removeFromStockById".
(note that it's important to do things in this order, because source item must still exists when you use it as the origin of the slide).

'''Situation C''':

When you move a card from a stock item to something that is not a stock item:
* insert the card as a classic HTML template (dojo.place / this.format_block).
* place it on the Stock item with "this.placeOnObject", using Stock item HTML id (see above).
* slide it to its new position with "this.slideToObject"
* remove the card from the Stock item with "removeFromStockById".

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

Stock

2014-02-24T18:05:47Z

Een:

"Stock" is a javascript component that you can use on your game interface to display a set of elements of the same size that need to be arranged in one or several lines.

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

Stock is used for example:
* To display set of cards, typically hands (ex: in Hearts, Seasons, The Boss, Race for the Galaxy, ...).
* To display items in player panels (ex: Takenoko, Amyitis, ...)
* ... in many other situations. For example, black dice and cubes on cards in Troyes are displayed with stock components.

Using stock:
* Your items are arranged nicely and sorted by type.
* When adding (or removing) items to the set. All items slide smoothly to their new position in the set to host the new one.
* Select/unselect items is a built-in functionnality.
* You don't have to care about inserting/removing HTML piece of code: the entire life of the stock is managed by the component.

== Using stock: a simple example ==

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

At first, don't forget to add "ebg/stock" as a dependency:
<pre>
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/stock" /// <==== HERE
],
</pre>

The stock is initialized in Javascript "setup" method like this:
<pre>
// Player hand
this.playerHand = new ebg.stock();
this.playerHand.create( this, $('myhand'), this.cardwidth, this.cardheight );
</pre>

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

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

Here's how we tell stock what are the items type to display:
<pre>
// Explain there are 13 images per row in the CSS sprite image
this.playerHand.image_items_per_row = 13;

// Create cards types:
for( var color=1;color<=4;color++ )
{
for( var value=2;value<=14;value++ )
{
// Build card type id
var card_type_id = this.getCardUniqueId( color, value );
this.playerHand.addItemType( card_type_id, card_type_id, g_gamethemeurl+'img/cards.jpg', card_type_id );
}
}
</pre>

Explanations:
* At first, we tell the stock component that our CSS sprite contains 13 items per row. This way, it can find the correct image for each card type id.
* Then for the 4x13 cards, we call "addItemType" method that create the type. The arguments are the type id, the weight of the card (for sorting purpose), the URL of our CSS sprite, and the position of our card image in the CSS sprite.

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

From now, if we need to add - for example - the 5 of Heart to player's hand, we can do this.
this.playerHand.addToStock( this.getCardUniqueId( 2 /* 2=hearts */, 5 ) );

In reality, cards have some IDs, which are useful to manipulate them. This is the reason we are using "addToStockWithId" instead:
this.playerHand.addToStock( this.getCardUniqueId( 2 /* 2=hearts */, 5 ), my_card_id );

If afterwards we want to remove this card from the stock:
this.playerHand.removeFromStockById( my_card_id );

== Complete stock component reference ==

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

With create, you create a new stock component.
Parameters:
* page: the container page. Usually: "this".
* container_div: the container "<div>" element (a void <div> element in your template, with an id).
* a stock item width and height, in pixels.

(See "Hearts" example above).

'''count():'''

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

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

Define a new type of item to the stock.

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

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

Be careful: you must specify the image url as this:
<pre>
g_gamethemeurl+'img/yourimage.png'
</pre>
* image_position: if "image" specify the URL of a CSS sprite, you must specify the position of the item image in this CSS sprite. For example, if you have a CSS sprite with 3 cubes with a size of 20x20 pixels each (so your CSS image has for example a size of 20x60 or 60x20), you specify "0" for the first cube image, 1 for the second, 2 for the third.
Important: there are more than one line of items in your CSS sprite, you must specify how many items per line you have in your CSS sprite like this:
<pre>
// Specify that there is 10 image items per row in images used in "myStockObject" control.
this.myStockObject.image_items_per_row = 10;
</pre>

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

Add an item to the stock, with the specified type.

To make your life easy, in most of the case we suggest you to use "addToStockWithId" in order to give an ID to the item added. "addToStock" is perfect when you are using a stock controls with items that are generic game material that does not need to be addressed individually (ex: a bunch of money tokens).

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

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

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

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

This is exactly the same method than "addToStock", except that you associate an ID to the newly created item.

This is especially useful:
* When you need to know which item(s) has been selected by the user (see "getSelectedItems").
* When you need to remove a specific item from the stock with "removeFromStockById"

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

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

Remove an item of the specific type from the stock.

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

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

Remove an item with a specific ID from the stock.

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

'''removeAll()'''

Remove all items from the stock.

'''getPresentTypeList()'''

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

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

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

'''resetItemsPosition()'''

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

'''item_margin'''

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

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

'''changeItemsWeight( newWeights )'''

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

Items are immediately re-sorted with the new weight.

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

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

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

'''setSelectionMode( mode )'''

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

'''isSelected( id )'''

Return true/false wether the specified item id has been selected or not.

'''selectItem( id )'''

Select the specified item.

'''unselectItem( id )'''

Unselect the specified item.

'''unselectAll()'''

Unselect all items of the stock.

'''onChangeSelection'''

This callback method is called when the player select/unselect an item of the stock.

You can connect this to one of your method like this:
<pre>
dojo.connect( this.myStockControl, 'onChangeSelection', this, 'onMyMethodToCall' );

(...)

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

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

Note: The "control_name" argument is the ID (the "DOM" id) of the <div> container of your stock control. Using "control_name", you can use the same callback method for different Stock control and see which one trigger the method.

'''getSelectedItems()'''

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

'''getUnselectedItems()'''

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

'''getAllItems()'''

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

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

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

By default, horizontal_overlap and vertical_overlap are 0.

When horizontal_overlap=20, it means that a stock item must overlap on 20% of the width of the previous item. horizontal_overlap can't be over 100.

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

See "Jaipur" game to see an example to use of this function.

'''onItemCreate'''

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

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

(...)

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

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

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

</pre>

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

The usual way is the following:

'''Situation A''':

When you add a card to a stock item, and this card is '''not''' coming from another stock: use "addToStockWithId" with a "from" argument set to the element of your interface where card should come from.

'''Situation B''':

When you add a card to a stock item, and this card is coming from another stock:
* on the destination Stock, use "addToStockWithId" with a "from" equals to the HTML id of the corresponding item in the source Stock. For example, If the source stock id is "myHand", then the HTML id of card 48 is "myHand_item_48".
* then, remove the source item with "removeFromStockById".
(note that it's important to do things in this order, because source item must still exists when you use it as the origin of the slide).

'''Situation C''':

When you move a card from a stock item to something that is not a stock item:
* insert the card as a classic HTML template (dojo.place / this.format_block).
* place it on the Stock item with "this.placeOnObject", using Stock item HTML id (see above).
* slide it to its new position with "this.slideToObject"
* remove the card from the Stock item with "removeFromStockById".

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

Game interface logic: yourgamename.js

2014-02-24T17:49:33Z

Een: /* Scoring dialogs */

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

Faq

2014-02-22T19:51:24Z

Een:

[[Category:Help]]

== General questions ==

===What is Board Game Arena?===

Board Game Arena (BGA) is an online board game platform. With BGA, you can play online and in real time against players from the whole world. A selection of various board games and card games is available. In order to play, the only thing you need is your browser!

===What do you mean by "real time play"?===

You can find many websites where you can play board games with a "turn based" approach: after each move, you have to wait for your opponents to connect to the website and play their own move. Most of the time, you have to wait a long time between each move, and games take a long time to finish (if they ever do).

On Board Game Arena, your opponents are connected to the game platform all along the game, and they can see your moves and react to them immediately - as is the case in the real world.

===What do I need to play?===

Your browser ... and that's it!

Board Game Arena does not require anything else on your computer. Thus, you can play from any computer, anywhere, anytime!

In order to make this thing possible, we are using the very latest technologies available for the web. This is the reason you should play with the most up to date web browsers to enjoy an optimal BGA experience (read more about our [[Browser_support|browser policy]]).

===How much does it cost to play on BGA?===

Playing on BGA is free.

You can also choose to help us by making a donation and becoming a [http://en.boardgamearena.com/#!club Board Game Arena club] member.

===What are the games available on BGA?===

Board Game Arena proposes a various selection of board and card games, but is specialized in modern ("European style") adult games.

[http://en.boardgamearena.com/#!gamelist See available games].

===What can I do if I have an issue with the website?===

Most of the issues one can encounter on this website should be solved with a simple web page refresh (or "F5").

If you experience persistent issues, you can browse the [http://forum.boardgamearena.com/viewforum.php?f=4 bug section in the forum], see if someone already reported the issue, and add a new bug report if that's not the case. Please take some time to describe the bug you are reporting in detail so that we can quickly reproduce and fix it.

===What is the legal status of this website?===

All the games currently available on this site have been licensed or otherwise authorized by copyright holders. Please be aware that games available on BGA can be removed at the copyright holders demand (for example: if they publish their own adaptation of the game).

Board Game Arena would like to thank all game publishers and game designers who allow us to have their games here, thus making it possible for this website to exist.

===I'm a game publisher: why would I like to have my game on Board Game Arena?===

The main goal of Board Game Arena is to make it easy for people to discover and love new games. We think that there is only two kinds of players on Board Game Arena: those who already bought the games they are playing online, and those who dream to buy them soon!

As the activity of this website contributes to increasing a game's popularity and thus generates game boxes sales in the "real world", we think it is beneficial to the boardgame community: people from all over the world can play online, we can have fun developing this game platform to the best of our ability, and game publishers get money from the box sales and build a special relationship with their players community.

== Meeting players and starting games ==

===I launched a new table but nobody is joining?===

Although Board Game Arena has been enjoying a growing popularity, it is still a young website. For the most popular games, you can find players at any time of the day. For other games, we advise you to come back at peak hour (around 22:00 CEST) if you can't find opponents at the moment.

Tip: check the number of online/available players for a game before launching the table.

===I joined a game. When does the game start?===

Each table has an administrator, which is the table creator. It is the responsibility of the table administrator to start the game when he is satisfied with the number of players having joined the table.

If you are the table administrator and can't launch the game, most of the time it's because there is not yet enough players joined the table.

===What is the meaning of the small color circle next to players names?===

* http://fr.boardgamearena.com/theme/img/status/online_.png : this player is active. He completed an action very recently.
* http://fr.boardgamearena.com/theme/img/status/inactive_.png : this player is inactive. He is connected to the website but did not perform any action recently.
* http://fr.boardgamearena.com/theme/img/status/offline_.png : this player is offline.

===What does the '% hits' statistic mean?===
% hits = number of victory points / number of games played

Where number of victory points is the following:
* When you win a 2 players game: 1 point.
* When you win a 3 players game: 1.5 points.
* When you win a 4 players game: 2 points.
* etc.

This way, "50%" means that you win 50% of 2 players game, or 33% of 3 players game, etc.

== During the game ==

===What is the meaning of the icons next to players names?===

* http://fr.boardgamearena.com/theme/img/layout/active_player.gif : this player must make a move now.
* http://fr.boardgamearena.com/theme/img/layout/active_player_clockalert.gif : this player must make a move now, and he has spent his reflexion time. Can someone wake him up? ;)
* http://fr.boardgamearena.com/theme/img/layout/active_player_nonack.gif : this player must make a move now, but is probably not aware of the fact. If the situation does not evolve, it might be that this player has some connection issue.
* http://fr.boardgamearena.com/theme/img/common/zombie.png : this player is a "zombie" (he left the game or has been fired from the game). The game goes on without this player.

When the "normal" avatar of a player is displayed, it means that this player is waiting for his turn to play.

===A player has to make a move but he/she doesn't. What can I do?===

* First, please remember that this player has the right to think as long as he needs to about is next move... well as long as he still has some time left on the game clock, that is.
* Then you can ask this player to confirm that he is still thinking about how to play.
* If this player seems to be away, we advise you to wait a few minutes: this player may be experiencing some network problems or have left his computer temporarily.
* If the player is not coming back, you can expel him from the game as soon as he is running out of time on the game clock for the current move (red bar) or if he goes over his alloted time to think by more than 3/4/5 minutes (depending on game speed). See Clock section for details. Important: in this case, no ELO points will be won by anybody for this game.

===What is the current progression of the game I'm playing?===

A percentage of progression is displayed on the top of the web page.
There is also a progress bar at the bottom of the web page shows you the current progression of the game.

===What is forbidden on Board Game Arena?===

* Leaving a game in progress on purpose.
* Taking an unnecessary and unreasonable amount of time at the end of game in an obvious losing situation.
* Kingmaking: enabling another player to win on purpose while there is a better move to make for yourself.
* Running out of time on the game clock.
* Giving some piece of information about the current game situation that corrupts the normal game flow.
* Communicating with another player about the game privately (ex: with MSN).
* Provocation / triumphalism / defeatism ... anything which is not fair play.
* Having a shocking avatar (no advertisement, no politics, ...)

Going against these rules will affect your reputation.

===What is absolutely forbidden in Board Game Arena?===

* Creating multiple accounts and playing against oneself.
* Insulting other players in any manner.

Going against these rules can lead to the removal of your account and/or to the blacklisting of your IP.

===What if some player does something wrong?===

The Board Game Arena platform has been designed to encourage players to maintain good behavior. The reputation system allows you to distinguish between good and bad players. Then, it is up to you to decide whether to start a game with them or not.

If you think some player has had bad behavior during a game, you can give him a at the end of the game.

If you think some player committed some serious wrongdoing during a game (ex: insult), please report this player to us ("report this player" link from his profile or game result page) so that we can take appropriate measures.

Contact us

2013-12-18T21:14:23Z

Een: Reverted edits by Januszk0 (talk) to last revision by 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.

== Postal address ==

G. Isabelli

19 bd république

92 260 Fontenay-aux-Roses

FRANCE

+33 6 17 25 80 34

BGA Game licences

2013-10-01T20:56:18Z

Een: moved BGA Game licences to BGA Game licenses: typo

#REDIRECT [[BGA Game licenses]]

BGA Game licenses

2013-10-01T20:56:18Z

Een: moved BGA Game licences to BGA Game licenses: typo

== What is a "license" exactly? ==

Almost all games on the Board Game Arena platform are adaptations of existing commercial "real" board games. In order to host an adaptation of one of these board games on a website, the copyright owners must first grant a license/authorisation to this website.

== Are all games on BGA licensed by their respective copyright owners? ==

Yes, for all games that are not in the public domain, BGA has been granted an authorisation to create and host an online version.

== Where can I find a list of games for which a license has already been granted? ==

[http://en.studio.boardgamearena.com/#!page/availablelicences Check the list of available licenses]

(NB: this page is restricted to developers registered in BGA studio. You'll need to enter your BGA studio credentials to access it)

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

We allow developers to start any project in the Studio. But when you submit your project to go live on BGA, it will be rejected during the review process if BGA doesn't hold a proper license for the game.

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

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

Great! :)

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

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

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

The copyright owners have to give an license/authorisation to BGA.

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

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

== Why aren't all the best-selling games that I love on that list? ==

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

So if you are thinking about a very popular game that is not on this list, the reason is most likely "we asked but it was not possible" and not "we didn't think of it".

We are really happy to have been able to build a very nice platform that managed to convince some of the most prestigious publishers to host their games here, but of course we can't convince -everyone-.

== I want to make my prototype/unpublished game available 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 most likely won't get a big audience on BGA.
* we also advise you against developing your own game: games adaptation are better when there is a designer whose focus is on the gameplay and a developer whose focus is on the implementation.

So you definitely can develop your prototype/unpublished game on BGA, but we encourage you to think twice about it and do it only if you are in one/several of the situations 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 your game with a big number of players to fine-tune some minor things ("balance" of the game).

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

This is the most frequently asked question, so for a detailed answer please follow the white rabbit down these numbered instructions:

=== 0: ===

In any case: please, do not contact publishers without asking us before. Just put yourself in the shoes of a game publisher who just published a popular game: what would you think if you received 40 emails from 40 developers speaking about some "BGA platform" and wanting to build an adaptation on it?

Proceed to 1.

=== 1: ===

First, you should determine who is the owner of the digital rights of the game. Most of the time, this is the original publisher of the game. The original publisher is not always easy to find, because very often board games are translated and published in different 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 every time.
* very often, if two publishers are mentioned on a gamebox, the well-known publisher is the local publisher from your country and the other one is the original publisher.

Special case: if the game is themed with a prestigious licence (Star Wars, Lord of the Rings, some TV show, some well known novel...), you can stop here immediately: contracts between game publishers and prestigious licenses owners are very restrictive, and there is 99% chance that an online adaptation on BGA would be impossible to manage.

Continue to 2.

=== 2: ===

Read the list of publishers from the "available licenses" page to check if BGA is already working with this publisher.

If YES, proceed to 3.
If NO, jump to 4.

However, if the publisher is listed as "not working with BGA", you can stop here immediately. It happens that some publishers are not convinced or interested by online boardgaming and it is their right to think so. The BGA team regularly meets 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 in the list a game licensed by this publisher that is available to be developed or under development?

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 license for a game, the publisher naturally expects that this game will be developed and published online. So we develop and publish a game before asking for another.
If you really want to develop another game from this particular publisher, the best option for you is to help develop the game that is currently licensed and then ask us to request the game you'd like to develop.

If NO: just ask us which game you want to develop and we will be happy to ask the publisher for his authorisation.

=== 4: ===

We have never worked with this publisher before.

If you have already developed a game on BGA, we will be happy to contact the publisher to ask for an authorisation :)

If this is your first game on BGA, we advise you to start with a game already on the list. Why? Because unfortunately, some developers ask us to request a license, and then don't finish the development. When we ask for a license, we are more comfortable if you have already shown your ability to realise an adaptation.

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

BGA Game licenses

2013-10-01T20:54:58Z

Een:

BGA Game licenses

2013-10-01T20:52:40Z

Een:

== What's a "license" ==

Almost all games on the Board Game Arena platform are adaptations of existing commercial "real" board games. In order to host an adaptation of one of these board games on a website, the copyright owners must first grant a license/authorisation to this website.

== Are all games on BGA licensed by their respective copyright owners? ==

Yes, for all games that are not in the public domain, BGA has been granted an authorisation to create and host an online version.

== Where can I find a list of games for which a license has already been granted? ==

[http://en.studio.boardgamearena.com/#!page/availablelicences Check the list of available licenses]

(NB: this page is restricted to developers registered in BGA studio. You'll need to enter your BGA studio credentials to access it)

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

We allow developers to start any project in the Studio. But when you submit your project to go live on BGA, it will be rejected during the review process if BGA doesn't hold a proper license for the game.

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

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

Great! :)

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

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

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

The copyright owners have to give an license/authorisation to BGA.

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

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

== Why aren't all the best-selling games that I love on that list? ==

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

So if you are thinking about a very popular game that is not on this list, the reason is most likely "we asked but it was not possible" and not "we didn't think of it".

We are really happy to have been able to build a very nice platform that managed to convince some of the most prestigious publishers to host their games here, but of course we can't convince -everyone-.

== I want to make my prototype/unpublished game available 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 most likely won't get a big audience on BGA.
* we also advise you against developing your own game: games adaptation are better when there is a designer whose focus is on the gameplay and a developer whose focus is on the implementation.

So you definitely can develop your prototype/unpublished game on BGA, but we encourage you to think twice about it and do it only if you are in one/several of the situations 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 your game with a big number of players to fine-tune some minor things ("balance" of the game).

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

This is the most frequently asked question, so for a detailed answer please follow the white rabbit down these numbered instructions:

=== 0: ===

In any case: please, do not contact publishers without asking us before. Just put yourself in the shoes of a game publisher who just published a popular game: what would you think if you received 40 emails from 40 developers speaking about some "BGA platform" and wanting to build an adaptation on it?

Proceed to 1.

=== 1: ===

First, you should determine who is the owner of the digital rights of the game. Most of the time, this is the original publisher of the game. The original publisher is not always easy to find, because very often board games are translated and published in different 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 every time.
* very often, if two publishers are mentioned on a gamebox, the well-known publisher is the local publisher from your country and the other one is the original publisher.

Special case: if the game is themed with a prestigious licence (Star Wars, Lord of the Rings, some TV show, some well known novel...), you can stop here immediately: contracts between game publishers and prestigious licenses owners are very restrictive, and there is 99% chance that an online adaptation on BGA would be impossible to manage.

Continue to 2.

=== 2: ===

Read the list of publishers from the "available licenses" page to check if BGA is already working with this publisher.

If YES, proceed to 3.
If NO, jump to 4.

However, if the publisher is listed as "not working with BGA", you can stop here immediately. It happens that some publishers are not convinced or interested by online boardgaming and it is their right to think so. The BGA team regularly meets 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 in the list a game licensed by this publisher that is available to be developed or under development?

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 license for a game, the publisher naturally expects that this game will be developed and published online. So we develop and publish a game before asking for another.
If you really want to develop another game from this particular publisher, the best option for you is to help develop the game that is currently licensed and then ask us to request the game you'd like to develop.

If NO: just ask us which game you want to develop and we will be happy to ask the publisher for his authorisation.

=== 4: ===

We have never worked with this publisher before.

If you have already developed a game on BGA, we will be happy to contact the publisher to ask for an authorisation :)

If this is your first game on BGA, we advise you to start with a game already on the list. Why? Because unfortunately, some developers ask us to request a license, and then don't finish the development. When we ask for a license, we are more comfortable if you have already shown your ability to realise an adaptation.

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

Browser support

2013-10-01T19:11:36Z

Een:

<h3>For the best experience, we recommend:</h3>
* '''Google Chrome 10+''' [http://www.google.com/chrome Windows] [http://www.google.com/chrome?platform=mac Mac] [http://www.google.com/chrome?platform=linux Linux]
* '''Mozilla Firefox 4+''' [http://www.mozilla.org/products/firefox/ Windows] [http://www.mozilla.org/products/firefox/ Mac] [http://www.mozilla.org/products/firefox/ Linux]

Board Game Arena takes advantage of the most recent web technology to make it possible for you to play without installing anything on your computer: no software to download or update, no plugins to install, etc.
Consequently, to play you need to use a modern web browser. Generally speaking, the more recent your web browser is, the more pleasant your game experience on Board Game Arena will be.

This website makes intensive use of Javascript and your browser's graphics capabilities. Thus, if you want to have the best gaming experience with Board Game Arena, you should use one of the browsers listed above. However, we officially support the following browsers:

* Google Chrome 4+
* Mozilla Firefox 3.5+
* Internet Explorer 9+
* Safari 4+

(Note: We do NOT support playing on iPads or similar tablets.)

[[Category:Help]]

Faq

2013-10-01T19:06:03Z

Een: /* What do I need to play? */

[[Category:Help]]

== General questions ==

===What is Board Game Arena?===

Board Game Arena (BGA) is an online board game platform. With BGA, you can play online and in real time against players from the whole world. A selection of various board games and card games is available. In order to play, the only thing you need is your browser!

===What do you mean by "real time play"?===

You can find many websites where you can play board games with a "turn based" approach: after each move, you have to wait for your opponents to connect to the website and play their own move. Most of the time, you have to wait a long time between each move, and games take a long time to finish (if they ever do).

On Board Game Arena, your opponents are connected to the game platform all along the game, and they can see your moves and react to them immediately - as is the case in the real world.

===What do I need to play?===

Your browser ... and that's it!

Board Game Arena does not require anything else on your computer. Thus, you can play from any computer, anywhere, anytime!

In order to make this thing possible, we are using the very latest technologies available for the web. This is the reason you should play with the most up to date web browsers to enjoy an optimal BGA experience (read more about our [[Browser_support|browser policy]]).

===How much does it cost to play on BGA?===

Playing on BGA is free.

You can also choose to help us by making a donation and becoming a [http://en.boardgamearena.com/#!club Board Game Arena club] member.

===What are the games available on BGA?===

Board Game Arena proposes a various selection of board and card games, but is specialized in modern ("European style") adult games.

[http://en.boardgamearena.com/#!gamelist See available games].

===What can I do if I have an issue with the website?===

Most of the issues one can encounter on this website should be solved with a simple web page refresh (or "F5").

If you experience persistent issues, you can browse the [http://forum.boardgamearena.com/viewforum.php?f=4 bug section in the forum], see if someone already reported the issue, and add a new bug report if that's not the case. Please take some time to describe the bug you are reporting in detail so that we can quickly reproduce and fix it.

===What is the legal status of this website?===

All the games currently available on this site have been licensed or otherwise authorized by copyright holders. Please be aware that games available on BGA can be removed at the copyright holders demand (for example: if they publish their own adaptation of the game).

Board Game Arena would like to thank all game publishers and game designers who allow us to have their games here, thus making it possible for this website to exist.

===I'm a game publisher: why would I like to have my game on Board Game Arena?===

The main goal of Board Game Arena is to make it easy for people to discover and love new games. We think that there is only two kinds of players on Board Game Arena: those who already bought the games they are playing online, and those who dream to buy them soon!

As the activity of this website contributes to increasing a game's popularity and thus generates game boxes sales in the "real world", we think it is beneficial to the boardgame community: people from all over the world can play online, we can have fun developing this game platform to the best of our ability, and game publishers get money from the box sales and build a special relationship with their players community.

== Meeting players and starting games ==

===I launched a new table but nobody is joining?===

Although Board Game Arena has been enjoying a growing popularity, it is still a young website. For the most popular games, you can find players at any time of the day. For other games, we advise you to come back at peak hour (around 22:00 CEST) if you can't find opponents at the moment.

Tip: check the number of online/available players for a game before launching the table.

===I joined a game. When does the game start?===

Each table has an administrator, which is the table creator. It is the responsibility of the table administrator to start the game when he is satisfied with the number of players having joined the table.

If you are the table administrator and can't launch the game, most of the time it's because there is not yet enough players joined the table.

===What is the meaning of the small color circle next to players names?===

* http://fr.boardgamearena.com/theme/img/status/online_.png : this player is active. He completed an action very recently.
* http://fr.boardgamearena.com/theme/img/status/inactive_.png : this player is inactive. He is connected to the website but did not perform any action recently.
* http://fr.boardgamearena.com/theme/img/status/offline_.png : this player is offline.

===What does the '% hits' statistic mean?===
% hits = number of victory points / number of games played

Where number of victory points is the following:
* When you win a 2 players game: 1 point.
* When you win a 3 players game: 1.5 points.
* When you win a 4 players game: 2 points.
* etc.

This way, "50%" means that you win 50% of 2 players game, or 33% of 3 players game, etc.

== During the game ==

===What is the meaning of the icons next to players names?===

* http://fr.boardgamearena.com/theme/img/layout/active_player.gif : this player must make a move now.
* http://fr.boardgamearena.com/theme/img/layout/active_player_clockalert.gif : this player must make a move now, and he has spent his reflexion time. Can someone wake him up? ;)
* http://fr.boardgamearena.com/theme/img/layout/active_player_nonack.gif : this player must make a move now, but is probably not aware of the fact. If the situation does not evolve, it might be that this player has some connection issue.
* http://fr.boardgamearena.com/theme/img/common/zombie.png : this player is a "zombie" (he left the game or has been fired from the game). The game goes on without this player.

When the "normal" avatar of a player is displayed, it means that this player is waiting for his turn to play.

===A player has to make a move but he/she doesn't. What can I do?===

* First, please remember that this player has the right to think as long as he needs to about is next move... well as long as he still has some time left on the game clock, that is.
* Then you can ask this player to confirm that he is still thinking about how to play.
* If this player seems to be away, we advise you to wait a few minutes: this player may be experiencing some network problems or have left his computer temporarily.
* If the player is not coming back, you can expel him from the game as soon as he is running out of time on the game clock for the current move (red bar) or if he goes over his alloted time to think by more than 3/4/5 minutes (depending on game speed). See Clock section for details. Important: in this case, no ELO points will be won by anybody for this game.

===What is the current progression of the game I'm playing?===

A percentage of progression is displayed on the top of the web page.
There is also a progress bar at the bottom of the web page shows you the current progression of the game.

===What is forbidden on Board Game Arena?===

* Leaving a game in progress on purpose.
* Thinking an unnecessary and unreasonable amount of time at the end of game in an obvious losing situation.
* Kingmaking: enabling another player to win on purpose while there is a better move to make for yourself.
* Running out of time on the game clock.
* Giving some piece of information about the current game situation that corrupts the normal game flow.
* Communicating with another player about the game privately (ex: with MSN).
* Provocation / triumphalism / defeatism ... anything which is not fair play.
* Having a shocking avatar (no advertisement, no politics, ...)

Going against these rules will affect your reputation.

===What is absolutely forbidden in Board Game Arena?===

* Creating multiple account and playing against oneself.
* Insulting other players in any manner.

Going against these rules can lead to the removal of your account and/or to the blacklisting of your IP.

===What if some player does something wrong?===

Board Game Arena platform has been designed to encourage players to maintain a good behaviour. The reputation system allows you to distinguish between good and bad players. Then, it is up to you to decide whether to start a game with them or not.

If you think some player has had a bad behavior during a game, you can give him a at the end of the game.

If you think some player committed some serious wrongdoing during a game (ex: insult), please report this player to us ("report this player" link from his profile or game result page) so that we can take appropriate measures.

Privacy

2013-07-09T06:22:06Z

Een: Created page with "To create an account, you need to provide an email, user name and password. You can also complete your player profile with some other data. We store this data. Yep. It would ..."

To create an account, you need to provide an email, user name and password.
You can also complete your player profile with some other data.

We store this data. Yep. It would be pretty annoying for you to enter it each time you visit ;)

If you are 'internet paranoid' and you never provide any website with accurate personal information, congratulations! You can skip this section.

If you are not, congratulations! You can also skip this section which is intended only for 'internet paranoid' people anyway... It has been written for compliance with some social network authentication policy (take your bet, there is only two - oh, wait, if you are reading this you probably know). Well, to be fair, I could have left it empty too, the only check made by said social network being that the page exists. But, what would have been the fun in that?

If you are still interested to read on some stuff instead of going straight to playing:
* Your password is stored encrypted, but the usual precautionary measures apply. You should use a strong password and not use the same one that for sensitive websites. Some people would say never to use the same password, but this looks like excessive blunt force to the head, except for websites with very sensitive information. Shouldn't be the case on a gaming website, but hey, do as you please.
* We don't share your email with third parties without your consent. Your consent may be implicit in some obvious cases (such as if you take part in a contest with prizes from a publisher, as it will be needed for the publisher to contact you to redeem the prize).
* Your profile information is visible to other players, as well as your gaming history on the website. So, since anyone can create an account on the site, it should be considered public information. But if you use a pseudonym for your username, it shouldn't be easy to link it to your real identity (in case you would be worried about that).

Hope this all sounds reasonable to you, and that you can now enjoy Board Game Arena without second thoughts!

Cheers and doughnuts,

The admins.

Game interface logic: yourgamename.js

2013-06-30T13:35:10Z

Een: /* 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 ).play();
</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>

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

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

2013-06-30T13:34:16Z

Een: /* 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" ).play();
</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>

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

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

Gamehelpelfenland

2013-06-16T13:00:56Z

Een: /* Goal of the game */

== Goal of the game ==

Visiting as many cities as possible in Elfenland over 4 rounds.

At the end of the 4th round, the player who collected the most Town Pieces wins.

We advise you to play with at least 3 players to best enjoy the game (4 or 5 is even better). A lot of the fun comes from using the Transportation Counters set by other players to optimise one's travels, so the more the merrier!

== Round overview ==

A round is split into phases:

# Each player fills his hand up to 8 cards and gets a secret Transportation Counter.
# One after another, each player chooses a Transportation Counter from the 5 visible or drawn from the facedown stack, until each player took 3.
# One after another, each player chooses must plan a travel road by laying a Transportation Counter matching the terrain of the chosen road. This phase goes on until each player has passed consecutively. Each player also owns an Obstacle that he can lay down on a Transportation Counter to up the cost of traveling on this road from 1 card.
# One after another, each player is going to travel from town to town. The current position of a player is shown by the Elf Boot of his color, initially set on the biggest town, Elvenhold.

At the end of the round, a player can keep a maximum of 4 cards in hand, and keeps only 1 Transportation counter.

== Travel rules ==

Players can travel :
* on the roads on which a Transportation Counter has been set
* on the rivers
* on the lakes.

To travel on a road, a river or a lake, the player needs to pay with the cards in hands the cost matching the terrain of the road and the means of transport used.

For example, if the Transportation Counter 'Magic Cloud' has been set on a mountain road, one can travel with just one 'Magic Cloud' card. But if it has been set on a forest or plain road, one needs to pay 2 'Magic Cloud' cards to pass (NB: the 'Magic Cloud' Transportation Counter cannot be used to travel in the desert, as it's too hot for a Cloud over there).

Also :
* To travel a river, you need only 1 'Raft' card to go downriver, but you need 2 to go upriver (look for the small arrows).
* To cross a lake, you need to pay two 'Raft' cards.
* If an Obstacle has been set on a road, you need to pay 1 more card of the appropriate type.
* If you don't have the appropriate cards to travel on a road, you can still pass using a 'Caravan', by paying 3 cards of any type (4 cards if there is an Obstacle on the road).

== Variant ==

In the 'Hometown' variant, each player gets a secret town card at the beginning of the game, telling him which town he has to reach at the end of the 4th round.

If he doesn't manage to get there, he'll lose as many points as the remaining distance he has to travel to get there.

This variant gives more tactic depth to the game, as you have to plan each round to the best to get the most Town Pieces while making sure to be able to get to your hometown at the end of the game.

'''Have a good game!'''

Gamehelpelfenland

2013-06-16T12:57:28Z

Een: /* Goal of the game */

== Goal of the game ==

Visiting as many cities as possible in Elfenland over 4 rounds.

At the end of the 4th round, the player who collected the most Town Pieces wins.

We advise you to play with at least 3 players to best enjoy the game (4 or 5 is even better). A lot of the fun comes from using the counters from other players to optimise one's travels, so the more the merrier!

== Round overview ==

A round is split into phases:

# Each player fills his hand up to 8 cards and gets a secret Transportation Counter.
# One after another, each player chooses a Transportation Counter from the 5 visible or drawn from the facedown stack, until each player took 3.
# One after another, each player chooses must plan a travel road by laying a Transportation Counter matching the terrain of the chosen road. This phase goes on until each player has passed consecutively. Each player also owns an Obstacle that he can lay down on a Transportation Counter to up the cost of traveling on this road from 1 card.
# One after another, each player is going to travel from town to town. The current position of a player is shown by the Elf Boot of his color, initially set on the biggest town, Elvenhold.

At the end of the round, a player can keep a maximum of 4 cards in hand, and keeps only 1 Transportation counter.

== Travel rules ==

Players can travel :
* on the roads on which a Transportation Counter has been set
* on the rivers
* on the lakes.

To travel on a road, a river or a lake, the player needs to pay with the cards in hands the cost matching the terrain of the road and the means of transport used.

For example, if the Transportation Counter 'Magic Cloud' has been set on a mountain road, one can travel with just one 'Magic Cloud' card. But if it has been set on a forest or plain road, one needs to pay 2 'Magic Cloud' cards to pass (NB: the 'Magic Cloud' Transportation Counter cannot be used to travel in the desert, as it's too hot for a Cloud over there).

Also :
* To travel a river, you need only 1 'Raft' card to go downriver, but you need 2 to go upriver (look for the small arrows).
* To cross a lake, you need to pay two 'Raft' cards.
* If an Obstacle has been set on a road, you need to pay 1 more card of the appropriate type.
* If you don't have the appropriate cards to travel on a road, you can still pass using a 'Caravan', by paying 3 cards of any type (4 cards if there is an Obstacle on the road).

== Variant ==

In the 'Hometown' variant, each player gets a secret town card at the beginning of the game, telling him which town he has to reach at the end of the 4th round.

If he doesn't manage to get there, he'll lose as many points as the remaining distance he has to travel to get there.

This variant gives more tactic depth to the game, as you have to plan each round to the best to get the most Town Pieces while making sure to be able to get to your hometown at the end of the game.

'''Have a good game!'''

Gamehelpelfenland

2013-06-16T12:52:46Z

Een: /* Round overview */

== Goal of the game ==

Visiting as many cities as possible in Elfenland over 4 rounds.

At the end of the 4th round, the player who collected the most Town Pieces wins.

== Round overview ==

A round is split into phases:

# Each player fills his hand up to 8 cards and gets a secret Transportation Counter.
# One after another, each player chooses a Transportation Counter from the 5 visible or drawn from the facedown stack, until each player took 3.
# One after another, each player chooses must plan a travel road by laying a Transportation Counter matching the terrain of the chosen road. This phase goes on until each player has passed consecutively. Each player also owns an Obstacle that he can lay down on a Transportation Counter to up the cost of traveling on this road from 1 card.
# One after another, each player is going to travel from town to town. The current position of a player is shown by the Elf Boot of his color, initially set on the biggest town, Elvenhold.

At the end of the round, a player can keep a maximum of 4 cards in hand, and keeps only 1 Transportation counter.

== Travel rules ==

Players can travel :
* on the roads on which a Transportation Counter has been set
* on the rivers
* on the lakes.

To travel on a road, a river or a lake, the player needs to pay with the cards in hands the cost matching the terrain of the road and the means of transport used.

For example, if the Transportation Counter 'Magic Cloud' has been set on a mountain road, one can travel with just one 'Magic Cloud' card. But if it has been set on a forest or plain road, one needs to pay 2 'Magic Cloud' cards to pass (NB: the 'Magic Cloud' Transportation Counter cannot be used to travel in the desert, as it's too hot for a Cloud over there).

Also :
* To travel a river, you need only 1 'Raft' card to go downriver, but you need 2 to go upriver (look for the small arrows).
* To cross a lake, you need to pay two 'Raft' cards.
* If an Obstacle has been set on a road, you need to pay 1 more card of the appropriate type.
* If you don't have the appropriate cards to travel on a road, you can still pass using a 'Caravan', by paying 3 cards of any type (4 cards if there is an Obstacle on the road).

== Variant ==

In the 'Hometown' variant, each player gets a secret town card at the beginning of the game, telling him which town he has to reach at the end of the 4th round.

If he doesn't manage to get there, he'll lose as many points as the remaining distance he has to travel to get there.

This variant gives more tactic depth to the game, as you have to plan each round to the best to get the most Town Pieces while making sure to be able to get to your hometown at the end of the game.

'''Have a good game!'''

Gamehelpelfenland

2013-06-16T12:50:55Z

Een: Created page with "== Goal of the game == Visiting as many cities as possible in Elfenland over 4 rounds. At the end of the 4th round, the player who collected the most Town Pieces wins. == R..."

== Goal of the game ==

Visiting as many cities as possible in Elfenland over 4 rounds.

At the end of the 4th round, the player who collected the most Town Pieces wins.

== Round overview ==

A round is split into phases:

# Each player fills his hand up to 8 cards and gets a secret Transportation Counter.
# One after another, each player chooses a Transportation Counter from the 5 visible or drawn from the facedown stack, until each player took 3.
# One after another, each player chooses must plan a travel road by laying a Transportation Counter matching the terrain of the chosen road. This phase goes on until each player has passed consecutively. Each player also owns an Obstacle that he can lay down on a Transportation Counter to up the cost of traveling on this road from 1 card.
# One after another, each player is going to travel from town to town. The current position of a player is shown by the Elf Boot of his color, initially set on the biggest town, Elvenhold.

== Travel rules ==

Players can travel :
* on the roads on which a Transportation Counter has been set
* on the rivers
* on the lakes.

To travel on a road, a river or a lake, the player needs to pay with the cards in hands the cost matching the terrain of the road and the means of transport used.

For example, if the Transportation Counter 'Magic Cloud' has been set on a mountain road, one can travel with just one 'Magic Cloud' card. But if it has been set on a forest or plain road, one needs to pay 2 'Magic Cloud' cards to pass (NB: the 'Magic Cloud' Transportation Counter cannot be used to travel in the desert, as it's too hot for a Cloud over there).

Also :
* To travel a river, you need only 1 'Raft' card to go downriver, but you need 2 to go upriver (look for the small arrows).
* To cross a lake, you need to pay two 'Raft' cards.
* If an Obstacle has been set on a road, you need to pay 1 more card of the appropriate type.
* If you don't have the appropriate cards to travel on a road, you can still pass using a 'Caravan', by paying 3 cards of any type (4 cards if there is an Obstacle on the road).

== Variant ==

In the 'Hometown' variant, each player gets a secret town card at the beginning of the game, telling him which town he has to reach at the end of the 4th round.

If he doesn't manage to get there, he'll lose as many points as the remaining distance he has to travel to get there.

This variant gives more tactic depth to the game, as you have to plan each round to the best to get the most Town Pieces while making sure to be able to get to your hometown at the end of the game.

'''Have a good game!'''

Moderationpolicy

2013-05-30T19:13:08Z

Een: /* 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: porn, 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 (porn, 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
|-

|}

Moderationpolicy

2013-05-30T18:52:46Z

Een: /* Player profile influence */

== 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: porn, 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 (porn, 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 notice 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 have 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 voluntee 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. This 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 adress, 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
| Tranlation stealing / vandalism
| The player is writing inapropriate / 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 alloted 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

2013-05-30T18:52:15Z

Een: /* Player profile influence */

== 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 player.
* 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: porn, 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 (porn, 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 notice 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 have 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 voluntee 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. This 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 adress, 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
| Tranlation stealing / vandalism
| The player is writing inapropriate / 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 alloted 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

2013-05-30T18:44:44Z

Een: /* 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 gives 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 player.
* 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: porn, 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 (porn, 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 notice 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 have 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 voluntee 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. This 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 adress, 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
| Tranlation stealing / vandalism
| The player is writing inapropriate / 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 alloted 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

2013-05-30T18:44:30Z

Een: /* 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 time 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 gives 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 player.
* 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: porn, 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 (porn, 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 notice 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 have 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 voluntee 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. This 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 adress, 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
| Tranlation stealing / vandalism
| The player is writing inapropriate / 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 alloted 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
|-

|}

Practical debugging

2013-05-19T20:14:01Z

Een: /* Add traces to your code */

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

== Tools ==

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

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

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

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

To debug with Internet Explorer, we advise you to use one of the most recent version (ex: IE9). Last versions of Internet Explorer have way better development tools than the previous ones...

== General tip for debugging ==

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

You can save up to 3 different states.

== Debugging my game when it cannot start ==

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

If the error is not explicitly displayed when you click on "Express start", you should check the "Gameserver error log" in the [[Studio_back-office|Studio backoffice]].

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

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

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

Example:
<pre>

// (...my code to debug)

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

// (...my code to debug)

</pre>

=== Add traces to your code ===

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

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

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

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

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

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

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

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

== Debugging my HTML/CSS layout ==

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

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

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

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

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

== Debugging my Javascript game interface logic ==

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

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

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

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

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

Note: check Reversi example for this.

=== Add traces in your code ===

You can use the following:

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

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

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

'''alert( variable_to_inspect )'''

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

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

== Some frequent errors ==

=== when launching the game "Fatal error during creation of database ebd_quoridor_389 Not logged." ===

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

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

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

=== when refreshing the web page, the interface remains on "Application loading..." ===

In this case, you probably have a syntax error in your Javascript code, and the interface refuses to load.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Practical debugging

2013-05-19T19:32:34Z

Een: /* Debugging my PHP game logic (or my view) */

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

== Tools ==

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

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

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

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

To debug with Internet Explorer, we advise you to use one of the most recent version (ex: IE9). Last versions of Internet Explorer have way better development tools than the previous ones...

== General tip for debugging ==

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

You can save up to 3 different states.

== Debugging my game when it cannot start ==

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

If the error is not explicitly displayed when you click on "Express start", you should check the "Gameserver error log" in the [[Studio_back-office|Studio backoffice]].

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

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

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

Example:
<pre>

// (...my code to debug)

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

// (...my code to debug)

</pre>

=== Add traces to your code ===

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

'''self::debug( $message )'''

'''self::trace( $message )'''

'''self::warn( $message )'''

'''self::error( $message )'''

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

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

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

== Debugging my HTML/CSS layout ==

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

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

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

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

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

== Debugging my Javascript game interface logic ==

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

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

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

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

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

Note: check Reversi example for this.

=== Add traces in your code ===

You can use the following:

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

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

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

'''alert( variable_to_inspect )'''

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

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

== Some frequent errors ==

=== when launching the game "Fatal error during creation of database ebd_quoridor_389 Not logged." ===

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

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

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

=== when refreshing the web page, the interface remains on "Application loading..." ===

In this case, you probably have a syntax error in your Javascript code, and the interface refuses to load.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Translations

2013-05-10T19:54:03Z

Een: /* On client side (Javascript) */

Using BGA Studio, the game you create is ready to be translated to each language by the BGA community. To make this possible, you only need to specify which string must be translated and how to combine them.

== How translation works? ==

When developing your game, all strings must be in English. Strings must be coherent with the English version of the game.

Before the release of the game, BGA team will do the French translation of the game.

After the release of the game, the BGA players community will translate the game in every language.

== What should be translated? ==

Every text that can be visible by the player when the game is running normally. This includes tooltips, texts on cards, error messages, ...

This does NOT include error messages that are not supposed to happened (unexpected errors).

== Focus on translating notifications ==

Usually, translating a website is simple: you just call a function on every string you have to translate, and the string is translated in the player's language. On Board Game Arena, this is exactly the same with the "_( string )" function.

However, there is one difference on BGA: notifications. The server is sending notifications to players, and most of the time the notifications are the same for every players, no matter what language each player is using. This is why notifications are translated on client side in the proper language, even if the strings are defined on server side.

== WARNING: how to make sure your strings will be translated ==

For each game, our translation tool is doing a full scan of the code, looking for translator markers like "_()" or "clientranslate()"... (see below the list of translation markers).

If your original string is not "physically" inside one of this marker, it won't be translated.

<pre>
// Examples: the following strings will be translated:
var mystring_translated = _("my string"); // JS
$mystring_translated = self::_("my string"); // PHP
$mystring_translated = sprintf( _("my string with an %s argument"), $argument ); // PHP

// Examples: the following strings WILL NOT be translated:
$my_string = "my string";
$not_translated = self::_( $my_string ); // The original string is not bordered by a translator marker => no translation
$not_translated = self::_( sprintf( "my string with a %s argument", $argument ) ); // Same thing
</pre>

== How to not make translators crazy ;) ==

* When you need the same string twice, try to reuse exactly the same string (with the same case) to minimize the number of strings.
* Do not mark as translatable a game element that does not have to be translated (ex: if the name of a monster on a card is "Zzzzz", maybe there's no need to translate it).
* Words does not come in the same order in each language. Thus, when you have to translate a string with an argument, do not write something like:
<pre>_("First part of the string, ").$argument.' '._("second part of the string")</pre>
Write instead:
<pre>sprintf( _("First part of the string, %s second part of the string"), $argument )</pre>
(or the equivalent "dojo.string.substitute" in Javascript)
* When translators are going to translate your game, the most difficult task for them is to get the context of the string to be translated. The more the string is a short insignificant string, the more difficult is the task for them. As a rule of thumb, try to avoid insignificant short strings.
* The BGA translation policy is to be flexible on grammar... We prefer to write "player gets 1 coin(s)" than write two versions of the same string for plural and singular - it reduces the number of strings to translate.
* Instead of writing nice strings like "With the effect of ZZZ, player XXX gets a new YYY", which is very difficult to translate, write strings like "ZZZ: XXX gets YYY".

== On client side (Javascript) ==

On client side, things are quite simple: you just have to use the "_()" function for all strings you want to translate.

Examples:
<pre>
// Get a string in player's language:
var translated = _("original english string");

// Get a string in player's language with parameter:
var translated = dojo.string.substitute( "You can pick ${p} cards and discard ${d}", {
p: 2,
d: 4
} );
</pre>

'''WARNING:''' in Javascript strings to translate, you should never use '\n', '\t' or such, as it will break the translation bundle and result in all the Javascript translation to fail. In any case, the strings will result in HTML code, and such character codes won't have any impact on the HTML rendering. You should use HTML markup instead.

== On server side (PHP) ==

On PHP side, you can use 3 different functions to specify that a string must be translated.

'''clienttranslate( "my string to translate" ):'''

This function is '''transparent''': it will return the original English string without any change. It's only purpose is to mark this string as "must be translated", and to make sure the translated version of the string will be available on client side.

In general, you use clienttranslate:
* On your states.inc.php, for field "description" and "descriptionmyturn".

<pre>
"description" => clienttranslate('${card_name}: ${actplayer} must discard 4 identical energies'),
</pre>

* On "material.inc.php", when defining texts for game material that must be displayed on client side.
<pre>
$this->card_types = array(

1 => array(
'name' => clienttranslate("Amulet of Air"), // Thus, we can use "_( card_name )" on Javascript side.
</pre>

* When sending a notification with "notifyAllPlayers" or "notifyPlayer", for the game log string and all game log arguments that need a translation.

<pre>
// A game log string with no argument:
self::notifyAllPlayers( 'pickLibraryCards', clienttranslate("Everyone draw cards from his library"), array() );
</pre>

Translating arguments is a little bit more complex. It is using the "i18n" special argument as below:

<pre>
// In the following example, we translate the game log itself, but also the "card_name" argument:

self::notifyAllPlayers( 'winPoints', clienttranslate('${card_name}: ${player_name} gains ${points} point(s)'), array(
'i18n' => array( 'card_name' ), // <===== We specify here that "card_name" argument must be transate
'player_id' => $player_id,
'player_name' => self::getActivePlayerName(),
'points' => $points,
'card_name' => $this->card_types[8]['name'] // <==== Here, we provide original English string.
) );
</pre>

'''self::_( "my string to translate" ):'''

This function returns a string translated in the language of CURRENT user (ie: player who send the request to the server) (be careful, this is NOT the active player).

Most of the time, you don't need to translate strings on server side, except on the following 3 situations:
* When throwing an exception because the player did a forbidden move.

<pre>
// This will display a translatable red message to the player that just do some wrong action:
throw new feException( self::_('You must choose 3 cards'), true);

// ... notice the use of "true" parameter that signal that this exception is "expected". In theory, all exception that are excepted should be translated.
</pre>

* In "yourgame.view.php", when creating the labels for the game interface used in your template (.tpl) file.

<pre>
$this->tpl['CARDS_FOR_YEAR_2'] = self::_("Your cards for year II");
</pre>

* Eventually, in your material.inc.php, if for example you need to use some string elements in your exceptions.

<pre>
// In material.inc.php, $this->energies[n]['nametr'] has been created with the self::_() method. This we can do this:
throw new feException( self::_("To execute this action you need more: ").' '.$this->energies[$resource_id]['nametr'], true );
</pre>

* Eventually, in your "getAllDatas" PHP method, as the data return by this method is used only by current user.

'''totranslate( "my string to translate" ):'''

This function works exactly like 'clienttranslate', except it tells BGA that the string is not needed on client side.

You should not use this function, except on the following cases:
* Statistics name in stats.inc.php
* Option names and option values name in gameoptions.inc.php

Scrollmap

2013-04-26T13:57:14Z

Een: /* Enable scrollmap zone extension */

Scrollmap is a BGA client side component to display an infinite game area.

In some games, players are building the main game area with tiles or cards. Examples:
* Carcassonne
* Saboteur
* Takenoko
* Taluva
* ...

Of course this cause an additional difficulty for the adaptation, because we have to display an infinite game area into a finite space on the screen. This is where Scrollmap component can help you.

== Scrollmap in action ==

If you want to see how Scrollmap looks like, please try "Saboteur" or "Takenoko" games on BGA, or watch a game in progress.

In both games, you can see that there are arrow controls around the main game area, so that players can use them to scroll the view. You can also drag'n'drop the game area to scroll.

== How to use Scrollmap ==

At first, don't forget to add "ebg/scrollmap" as a dependency:
<pre>
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/scrollmap" /// <==== HERE
],
</pre>

Then, declare a new variable in your class for the Scrollmap object:

<pre>
constructor: function(){
console.log('yourgame constructor');

// Scrollable area
this.scrollmap = new ebg.scrollmap();
</pre>

Now, open your template (TPL) file and add this HTML code:

<pre>
<div id="map_container">
<div id="map_scrollable"></div>
<div id="map_surface"></div>
<div id="map_scrollable_oversurface"></div>
<a id="movetop" href="#"></a>
<a id="moveleft" href="#"></a>
<a id="moveright" href="#"></a>
<a id="movedown" href="#"></a>
</div>
</pre>

There are also some lines to add to your CSS stylesheet. Please note that you can adapt it to your needs, especially the default width of the scrollable area:
<pre>
/** Scrollable area **/

#map_container {
position: relative;
width: 100%;
height: 400px;
overflow: hidden;
}
#map_scrollable, #map_scrollable_oversurface {
position: absolute;
top: 205px;
left: 315px;
}
#map_surface {
position: absolute;
top: 0px;
left: 0px;
width: 100%;
height: 100%;
cursor: move;
}
#map_footer {
text-align: center;
}

</pre>

Finally, to link your HTML code with your Javascript, place this in your Javascript "Setup" method:

<pre>
// Make map scrollable
this.scrollmap.create( $('map_container'),$('map_scrollable'),$('map_surface'),$('map_scrollable_oversurface') );
this.scrollmap.setupOnScreenArrows( 150 );

</pre>

This is it! Now, you should see on your game interface a scrollable game area. This is not really impressive though, because you didn't add anything on the game area yet. This is the next step.

== Scrollable area layers ==

There are 2 - and only 2 - places where you should place your HTML stuff in your scrollable area:
* inside "map_scrollable" div
* inside "map_scrollable_oversurface" div

The difference is very important: "map_scrollable" is beneath the surface that is used to drag'n'drop the game area, and "map_scrollable_oversurface" is above this surface. In practice:
* If some element on the game area need to be clicked (or any kind of user interaction), you should place it in map_scrollable_oversurface, otherwise no click can reach it.
* If some element on the game area don't need to be clicked, you'd better place it in "map_scrollable", so it is possible to drag'n'drop the game area from a point on this element.

Of course, all layers are scrolled synchronously.

Tips: in some situation, it's also useful to place a game element on map_scrollable and a corresponding invisible element over the surface to manage the interactions. Example: when an interactive element must be placed beneath a non interactive element for display reason.

== Positioning elements on game area ==

All elements on the game are must be absolute positioned (with "top" and "left" attributes).

By default, the game area is centered on 0,0 coordinates.

== Enable move arrows ==

To show move arrows icons around the scrollmap in order to enable click based navigation in addition to drag and drop, add these lines to your CSS:

<pre>
/** Move arrows **/

#movetop,#moveleft,#moveright,#movedown {
display: block;
position: absolute;
background-image: url('../../img/common/arrows.png');
width: 32px;
height: 32px;
}

#movetop {
top: 0px;
left: 50%;
background-position: 0px 32px;
}
#moveleft {
top: 50%;
left: 0px;
background-position: 32px 0px;
}
#moveright {
top: 50%;
right: 0px;
background-position: 0px 0px;
}
#movedown {
bottom: 0px;
left: 50%;
background-position: 32px 32px;
}
</pre>

In your javascript, define the following functions:

<pre>
onMoveTop : function( evt )
{
console.log( "onMoveTop" );
evt.preventDefault();
this.scrollmap.scroll( 0, 300 );
},
onMoveLeft : function( evt )
{
console.log( "onMoveLeft" );
evt.preventDefault();
this.scrollmap.scroll( 300, 0 );
},
onMoveRight : function( evt )
{
console.log( "onMoveRight" );
evt.preventDefault();
this.scrollmap.scroll( -300, 0 );
},
onMoveDown : function( evt )
{
console.log( "onMoveDown" );
evt.preventDefault();
this.scrollmap.scroll( 0, -300 );
},
</pre>

And connect onclick events on the arrows to these functions in your javascript setup

<pre>
dojo.connect( $('movetop'), 'onclick', this, 'onMoveTop' );
dojo.connect( $('moveleft'), 'onclick', this, 'onMoveLeft' );
dojo.connect( $('moveright'), 'onclick', this, 'onMoveRight' );
dojo.connect( $('movedown'), 'onclick', this, 'onMoveDown' );
</pre>

== Enable scrollmap zone extension ==

This is optional, when there can be unused screen space under the scrollmap that a player might want to use.
Add this in your .tpl after the scrollmap div (the matching css rules has already been defined):

<pre>
<div id="map_footer" class="whiteblock">
<a href="#" id="enlargedisplay">↓  {LABEL_ENLARGE_DISPLAY}  ↓</a>
</div>
</pre>

In your javascript, define the following function:

<pre>
onIncreaseDisplayHeight: function( evt )
{
console.log( '$$$$ Event : onIncreaseDisplayHeight' );
evt.preventDefault();

var cur_h = toint( dojo.style( $('map_container'), 'height' ) );
dojo.style( $('map_container'), 'height', ( cur_h+300 ) + 'px' );
},
</pre>

and connect them to the 'enlargedisplay' link in your setup:

<pre>
dojo.connect( $('enlargedisplay'), 'onclick', this, 'onIncreaseDisplayHeight' );
</pre>

In your view.php file, define the template variable LABEL_ENLARGE_DISPLAY so that it gets substituted with appropriate translatable text:

<pre>
$this->tpl['LABEL_ENLARGE_DISPLAY'] = self::_("Enlarge display");
</pre>

Scrollmap

2013-04-26T13:53:16Z

Een:

Studio FAQ

2013-04-25T20:03:11Z

Een: /* Should I use images free from copyright? */

This is a place where we will collect and answer frequently asked questions.

== What should I use to access the files through SFTP? ==

There is a lot of tools to do that. Use the one you are the most comfortable with.

On Linux Gnome, you can for example use the 'Connect to server' function of the Nautilus file management system, or use sshfs.

On Windows, there is for example the [http://winscp.net/ WinSCP client].

== I can't edit the files in my game directory, it looks like they are readonly. What's happening? ==

Maybe there is a maintenance operation underway.

If you don't get access back after some time (say one or two hours), please send us a mail to check.

== I can't access the Studio back-office, I get a 'Not authorized' error message? ==

You should first connect to the Studio website (with any of your <developer name><number> accounts). As the authentication is shared with the back-office, then you will be able to access it.

== I don't know the name to use to commit my game, what name should I use? ==

The game name for committing is the name of the game in lower case and without spaces or special characters (ex: puertorico).
It is the same name as the name used for the game folder in your SFTP access.

== What is the working language on BGA studio? ==

Working language is '''English'''.

Variables and functions must be named with English words.

Comments must be written in English.

Game interface strings and game logs must be written in English.

== How can I provide translation in my language? ==

BGA administrators will translate the game in French before the game release.

After the game release, the collaborative translation interface can be used to translate into other languages.

Check [[Translations]] to see how to make your game translatable.

== I updated the images in the 'img' folder of my game, but they don't show? ==

On BGA Studio, there is the gameserver you are developing on, and the main site server that is used to launch the games. The game icon, box and the publisher logo are hosted on the main site server, so they are not immediately available when you modify them on the gameserver. To deploy them on the main site, you have to use the [[Studio back-office]] to do a commit.

If the images still don't show after that, please try emptying your browser cache and reloading the page.

== I added some game options / some game statistics, but they don't show? ==

An extra deployment action from the BGA administrators is needed to activate new game options and statistics. Please contact us.

== Should I use images free from copyright? ==

If you are developing a game in the public domain, yes (or you can make your own if you feel it's better).

If you are developing a game for which we have a licence, we will usually provide art files from the publisher.

Studio FAQ

2013-04-25T20:01:50Z

Een:

This is a place where we will collect and answer frequently asked questions.

== What should I use to access the files through SFTP? ==

There is a lot of tools to do that. Use the one you are the most comfortable with.

On Linux Gnome, you can for example use the 'Connect to server' function of the Nautilus file management system, or use sshfs.

On Windows, there is for example the [http://winscp.net/ WinSCP client].

== I can't edit the files in my game directory, it looks like they are readonly. What's happening? ==

Maybe there is a maintenance operation underway.

If you don't get access back after some time (say one or two hours), please send us a mail to check.

== I can't access the Studio back-office, I get a 'Not authorized' error message? ==

You should first connect to the Studio website (with any of your <developer name><number> accounts). As the authentication is shared with the back-office, then you will be able to access it.

== I don't know the name to use to commit my game, what name should I use? ==

The game name for committing is the name of the game in lower case and without spaces or special characters (ex: puertorico).
It is the same name as the name used for the game folder in your SFTP access.

== What is the working language on BGA studio? ==

Working language is '''English'''.

Variables and functions must be named with English words.

Comments must be written in English.

Game interface strings and game logs must be written in English.

== How can I provide translation in my language? ==

BGA administrators will translate the game in French before the game release.

After the game release, the collaborative translation interface can be used to translate into other languages.

Check [[Translations]] to see how to make your game translatable.

== I updated the images in the 'img' folder of my game, but they don't show? ==

On BGA Studio, there is the gameserver you are developing on, and the main site server that is used to launch the games. The game icon, box and the publisher logo are hosted on the main site server, so they are not immediately available when you modify them on the gameserver. To deploy them on the main site, you have to use the [[Studio back-office]] to do a commit.

If the images still don't show after that, please try emptying your browser cache and reloading the page.

== I added some game options / some game statistics, but they don't show? ==

An extra deployment action from the BGA administrators is needed to activate new game options and statistics. Please contact us.

== Should I use images free from copyright? ==

If you are developing a game in the public domain, yes (or you can make your own if you feel it's better).
If you are developing a game for which we have a licence, we will usually provide art files from the publisher.

How to join BGA developer team?

2013-04-24T20:19:05Z

Een: ²

'''--- Notice ---'''
We have received a lot of positive feedback on the Studio, and lots of developers have registered.
We are very happy about it, but it comes with a cost in time spent answering emails and posts on the forum.
So please bear with us if we are slow to answer. As soon as we can, we will.
Thanks again for your interest!

Registering is done by e-mail at '''studio(at)boardgamearena.com'''.

Please provide the following information:
* your player user name on BGA
* your developer user name to be used on “BGA Studio” (for technical reasons, no space, number or special character);
* your real name;
* your e-mail address;
* your postal address.

We also drafted a quick [http://en.doc.boardgamearena.com/images/0/02/BGA_TC_Dev_en.pdf ''''terms & conditions' document''']. It's very light, so as to get to the fun part faster.

To be valid, the registration e-mail must contain this document as an attachment, with the following sentence in the mail body: ''''I agree with the terms & conditions for developers on BGA Studio joined as an attachment''''.

And of course, we also encourage you to tell us about your developer experience and which games you would love to develop on BGA!

== Ok, I registered, what do I get? ==

First, we'll discuss by e-mail the names of some of the games we have an agreement to develop, so that you can tell us 'Hey, this game is great! I want to develop it!' (please keep these names confidential, or it would ruin our tradition to make players guess the name of the next game on the forum)

Second, once we have discussed together and are set on a game you'll take charge of, we'll create your studio account and you will get:
* one login / password to access files through SFTP
* ten logins with numeric suffixes from 0 to 9 and a common simple password to test games on the studio website while developing.

Once logged in to your SFTP root folder, you will find:
* a ''''resources.html'''' file with the URLs to use and some extra connection information
* three folders containing the three simple games provided as examples
* a folder for the game you will be developing initialized after our 'EmptyGame' template, providing the game structure (and comments! and examples!)

Then... well that's all, you can start! See [[Studio#Great.2C_I.27m_in.21_..._How_should_I_start.3F|Great, I'm in! ... How should I start?]]

Zone

2013-04-20T17:42:40Z

Een:

The Zone component is meant to organise items of the same type inside a predefined space.

== Zone in action ==

If you want to see how Zone works, please try "Can't Stop" or "Niagara" on BGA, or watch a game in progress or game replay.

In Can't Stop, zone is used to display the bhikkus ascending the mountain when there is more than one on the same space (diagonal mode).

In Niagara, it is used to display the canoes over the circles going down the river (custom mode).

== How to use Zone ==

At first, don't forget to add "ebg/zone" as a dependency:
<pre>
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/zone" /// <==== HERE
],
</pre>

Then, declare a new variable in your class for the Zone object:

<pre>
constructor: function(){
console.log('yourgame constructor');

// Zone control
this.myZone = new ebg.scrollmap();
</pre>

Now, in your template file, you must add a div that will host this zone:

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

And set its width (and optionnaly, height and position) in CSS:

<pre>

#my_zone {
width: 100px;
}

</pre>

Then in your Javascript setup, attach your Zone component to the div and define its properties :

<pre>
zone.create( this, 'my_zone', <item_width>, <item_height> );
zone.setPattern( <mode> );
</pre>

* <item_width> is an integer for the width of the objects you want to organise in the zone
* <item_height> is an integer for the height of the objects you want to organise in the zone
* <mode> is one of 'grid' (objects will be put on lines from top left to bottom right, wrapping when there is not enough space left on the line) 'diagonal' (objects will be organised on a top left to bottom right diagonal, overlapping each other) or 'custom' (objects will be organised depending upon their number and the coordinates that you provide - see below)

Now your zone is ready to be used!

After creating an object that you want to add to the zone as a classic HTML template (dojo.place / this.format_block), you can simply use:

<pre>
zone.placeInZone( <object_id>, <weight> );
</pre>

* <object_id> is the string identifier for your object 'my_object_id'
* <weight> is an optional parameter used to sort items

To remove an item, use:

<pre>
zone.removeFromZone( <object_id>, <destroy?>, <to> );
</pre>

* <object_id> is the string identifier for your object 'my_object_id'
* <destroy?> is a boolean indicating if the object should be destroyed after being removed
* <to> is the destination the object must be slided to when being removed (before being eventually destroyed)

You can also:
* remove all items from the zone (and destroy them) using zone.removeAll();
* get the number of items in your zone using zone.getItemNumber();
* get an array of the ids of all the items using zone.getAllItems();

== Custom mode ==

If you want complete control on how your objects are laid out inside the Zone, you can determine their coordinates after their number when being added to the zone. Here is how to do it, when defining your Zone properties in the javascript setup:

<pre>
this.zone.setPattern( 'custom' );

this.zone.itemIdToCoords = function( i, control_width ) {
if( i%8==0 )
{ return { x:1,y:19, w:60, h:30 }; }
else if( i%8==1 )
{ return { x:30,y:38, w:60, h:30 }; }
else if( i%8==2 )
{ return { x:42,y:8, w:60, h:30 }; }
else if( i%8==3 )
{ return { x:5,y:58, w:60, h:30 }; }
else if( i%8==4 )
{ return { x:5,y:24, w:60, h:30 }; }
else if( i%8==5 )
{ return { x:35,y:43, w:60, h:30 }; }
else if( i%8==6 )
{ return { x:47,y:13, w:60, h:30 }; }
else if( i%8==7 )
{ return { x:10,y:63, w:60, h:30 }; }
};
</pre>

Zone

2013-04-20T17:38:13Z

Een:

Zone

2013-04-20T17:16:41Z

Een: Created page with "The Zone component is meant to organise items of the same type inside a predefined space. == Zone in action == If you want to see how Zone works, please try "Can't Stop" or ..."

Scrollmap

2013-04-20T16:23:55Z

Een:

Scrollmap

2013-04-20T16:13:01Z

Een:

Scrollmap is a BGA client side component to display an infinite game area.

In some games, players are building the main game area with tiles or cards. Examples:
* Carcassonne
* Saboteur
* Takenoko
* Taluva
* ...

Of course this cause an additional difficulty for the adaptation, because we have to display an infinite game area into a finite space on the screen. This is where Scrollmap component can help you.

== Scrollmap in action ==

If you want to see how Scrollmap looks like, please try "Saboteur" or "Takenoko" games on BGA, or watch a game in progress.

In both games, you can see that there are arrow controls around the main game area, so that players can use them to scroll the view. You can also drag'n'drop the game area to scroll.

== How to use Scrollmap ==

At first, don't forget to add "ebg/scrollmap" as a dependency:
<pre>
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/scrollmap" /// <==== HERE
],
</pre>

Then, declare a new variable in your class for the Scrollmap object:

<pre>
constructor: function(){
console.log('yourgame constructor');

// Scrollable area
this.scrollmap = new ebg.scrollmap();
</pre>

Now, open your template (TPL) file and add this HTML code:

<pre>
<div id="map_container">
<div id="map_scrollable"></div>
<div id="map_surface"></div>
<div id="map_scrollable_oversurface"></div>
<a id="movetop" href="#"></a>
<a id="moveleft" href="#"></a>
<a id="moveright" href="#"></a>
<a id="movedown" href="#"></a>
</div>
</pre>

There are also some lines to add to your CSS stylesheet. Please note that you can adapt it to your needs, especially the default width of the scrollable area:
<pre>
/** Scrollable area **/

#map_container {
position: relative;
width: 100%;
height: 400px;
overflow: hidden;
}
#map_scrollable, #map_scrollable_oversurface {
position: absolute;
top: 205px;
left: 315px;
}
#map_surface {
position: absolute;
top: 0px;
left: 0px;
width: 100%;
height: 100%;
cursor: move;
}
#map_footer {
text-align: center;
}

</pre>

Finally, to link your HTML code with your Javascript, place this in your Javascript "Setup" method:

<pre>
// Make map scrollable
this.scrollmap.create( $('map_container'),$('map_scrollable'),$('map_surface'),$('map_scrollable_oversurface') );
this.scrollmap.setupOnScreenArrows( 150 );

</pre>

This is it! Now, you should see on your game interface a scrollable game area. This is not really impressive though, because you didn't add anything on the game area yet. This is the next step.

== Scrollable area layers ==

There are 2 - and only 2 - places where you should place your HTML stuff in your scrollable area:
* inside "map_scrollable" div
* inside "map_scrollable_oversurface" div

The difference is very important: "map_scrollable" is beneath the surface that is used to drag'n'drop the game area, and "map_scrollable_oversurface" is above this surface. In practice:
* If some element on the game area need to be clicked (or any kind of user interaction), you should place it in map_scrollable_oversurface, otherwise no click can reach it.
* If some element on the game area don't need to be clicked, you'd better place it in "map_scrollable", so it is possible to drag'n'drop the game area from a point on this element.

Of course, all layers are scrolled synchronously.

Tips: in some situation, it's also useful to place a game element on map_scrollable and a corresponding invisible element over the surface to manage the interactions. Example: when an interactive element must be placed beneath a non interactive element for display reason.

== Positioning elements on game area ==

All elements on the game are must be absolute positioned (with "top" and "left" attributes).

By default, the game area is centered on 0,0 coordinates.

== Move arrows ==

To show move arrows around the scrollmap to enable click based navigation in addition to drag and drop, add these lines to your CSS

<pre>
/** Move arrows **/

#movetop,#moveleft,#moveright,#movedown {
display: block;
position: absolute;
background-image: url('../../img/common/arrows.png');
width: 32px;
height: 32px;
}

#movetop {
top: 0px;
left: 50%;
background-position: 0px 32px;
}
#moveleft {
top: 50%;
left: 0px;
background-position: 32px 0px;
}
#moveright {
top: 50%;
right: 0px;
background-position: 0px 0px;
}
#movedown {
bottom: 0px;
left: 50%;
background-position: 32px 32px;
}
</pre>

Then, in your javascript, define the following functions

<pre>
onMoveTop : function( evt )
{
console.log( "onMoveTop" );
evt.preventDefault();
this.scrollmap.scroll( 0, 300 );
},
onMoveLeft : function( evt )
{
console.log( "onMoveLeft" );
evt.preventDefault();
this.scrollmap.scroll( 300, 0 );
},
onMoveRight : function( evt )
{
console.log( "onMoveRight" );
evt.preventDefault();
this.scrollmap.scroll( -300, 0 );
},
onMoveDown : function( evt )
{
console.log( "onMoveDown" );
evt.preventDefault();
this.scrollmap.scroll( 0, -300 );
},
</pre>

And connect onclick events on the arrows to these functions in your javascript setup

<pre>
dojo.connect( $('movetop'), 'onclick', this, 'onMoveTop' );
dojo.connect( $('moveleft'), 'onclick', this, 'onMoveLeft' );
dojo.connect( $('moveright'), 'onclick', this, 'onMoveRight' );
dojo.connect( $('movedown'), 'onclick', this, 'onMoveDown' );
</pre>

Scrollmap

2013-04-20T16:08:47Z

Een: /* How to use Scrollmap */

Scrollmap

2013-04-20T16:06:32Z

Een: /* How to use Scrollmap */

First steps with BGA Studio

2013-04-13T13:41:24Z

Een: /* That's all! */

== Connect to your SFTP folder and to the BGA Studio website ==

After your account has been created, you will get by email:
* the name of the SFTP server to connect to
* your SFTP login and password
* ten BGA Studio logins ending with a numeral ranging from 0 to 9 and the password needed to use them.

Using this information:
# Connect to the SFTP server using your SFTP login and password, through your favourite SFTP client software (such as WinSCP for example)
# Check than in your home folder you have:
#* One folder for each of the three example games (reversi, hearts, gomoku)
#* One folder matching the game you will be developing
#* One 'resources.html' file
# Open the resources.html file, it contains
#* The URL pointing to the BGA Studio website (protected with an HTTP Basic authentication scheme, the login and password are also referenced in the 'resources.html' file
#* The URL pointing to the BGA Studio backoffice (please note that you must first be logged in on the BGA Studio website to be able to access the backoffice, as the authentication is shared between the two)
#* The URL pointing to the web administration tool for the BGA Studio database.
# Click on the URL to the BGA Studio website, enter the HTTP Basic credentials when prompted for them (and have your browser conveniently memorize them for you). Then you get to an home page just like the one of the main BGA website. Enter one of your ten BGA studio logins to connect as a user.

== Launch your game and check how to update it ==
# Find your game in the 'Play now' section and launch a table
# Use the 'I want between X and X' players to tick down the maximum players number to the minimum
# Click 'Express start': your game launches with the maximum number of players specified. It shows an empty canvas: in the game zone you just have a sentence 'This is your game interface. You can edit this HTML in your ".tpl" file.'.
# Switch to your SFTP home folder, go into your game folder. Edit the game_game.tpl file, and change this sentence to 'Hey, this is my first game!', then save.
# Go back to your browser and refresh, check that the game zone has updated.
# Click on the 'Exit game' icon on the top right, and in the popup choose 'Express game stop'. The game ends automatically and you are brought back to the table screen for this ended game.
# Switch to your game folder, go into the img folder and overwrite your game_box.png file with another image.
# Go back to your browser, '''empty your browser cache''', then refresh the page, and check that the game box image has been updated.

== Commit your changes ==

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

Here is how to go through your first commit:
# Go back to your browser tab showing the 'resources.html' file. Click on the URL pointing to the BGA Studio backoffice (do not log out of the BGA Studio website before doing so, or you will get a '''Not authorized''' error message as the authentication is shared);
# Click on the 'Sources' menu entry to show the commit form. Enter your game name (under the same form as the name of your game folder: lowercase, no spaces), enter your commit comment (such as 'My first commit') then hit the 'Submit' button;
# Check the log for errors, it should end with the following lines:

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

NB: you should also commit each time you make an change to your gameoptions.inc.php file or to your stats.inc.php file, as an extra deployment action is needed from us for these files to take effect. Please mention in your commit comment that you need us to deploy those files, or send us an email to ask us to do it.

== That's all! ==

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

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

First steps with BGA Studio

2013-04-13T13:41:04Z

Een: /* That's all for your first steps! */

== Connect to your SFTP folder and to the BGA Studio website ==

After your account has been created, you will get by email:
* the name of the SFTP server to connect to
* your SFTP login and password
* ten BGA Studio logins ending with a numeral ranging from 0 to 9 and the password needed to use them.

Using this information:
# Connect to the SFTP server using your SFTP login and password, through your favourite SFTP client software (such as WinSCP for example)
# Check than in your home folder you have:
#* One folder for each of the three example games (reversi, hearts, gomoku)
#* One folder matching the game you will be developing
#* One 'resources.html' file
# Open the resources.html file, it contains
#* The URL pointing to the BGA Studio website (protected with an HTTP Basic authentication scheme, the login and password are also referenced in the 'resources.html' file
#* The URL pointing to the BGA Studio backoffice (please note that you must first be logged in on the BGA Studio website to be able to access the backoffice, as the authentication is shared between the two)
#* The URL pointing to the web administration tool for the BGA Studio database.
# Click on the URL to the BGA Studio website, enter the HTTP Basic credentials when prompted for them (and have your browser conveniently memorize them for you). Then you get to an home page just like the one of the main BGA website. Enter one of your ten BGA studio logins to connect as a user.

== Launch your game and check how to update it ==
# Find your game in the 'Play now' section and launch a table
# Use the 'I want between X and X' players to tick down the maximum players number to the minimum
# Click 'Express start': your game launches with the maximum number of players specified. It shows an empty canvas: in the game zone you just have a sentence 'This is your game interface. You can edit this HTML in your ".tpl" file.'.
# Switch to your SFTP home folder, go into your game folder. Edit the game_game.tpl file, and change this sentence to 'Hey, this is my first game!', then save.
# Go back to your browser and refresh, check that the game zone has updated.
# Click on the 'Exit game' icon on the top right, and in the popup choose 'Express game stop'. The game ends automatically and you are brought back to the table screen for this ended game.
# Switch to your game folder, go into the img folder and overwrite your game_box.png file with another image.
# Go back to your browser, '''empty your browser cache''', then refresh the page, and check that the game box image has been updated.

== Commit your changes ==

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

Here is how to go through your first commit:
# Go back to your browser tab showing the 'resources.html' file. Click on the URL pointing to the BGA Studio backoffice (do not log out of the BGA Studio website before doing so, or you will get a '''Not authorized''' error message as the authentication is shared);
# Click on the 'Sources' menu entry to show the commit form. Enter your game name (under the same form as the name of your game folder: lowercase, no spaces), enter your commit comment (such as 'My first commit') then hit the 'Submit' button;
# Check the log for errors, it should end with the following lines:

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

NB: you should also commit each time you make an change to your gameoptions.inc.php file or to your stats.inc.php file, as an extra deployment action is needed from us for these files to take effect. Please mention in your commit comment that you need us to deploy those files, or send us an email to ask us to do it.

== That's all! ==

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

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

First steps with BGA Studio

2013-04-13T13:40:33Z

Een: /* Commit your changes */

== Connect to your SFTP folder and to the BGA Studio website ==

After your account has been created, you will get by email:
* the name of the SFTP server to connect to
* your SFTP login and password
* ten BGA Studio logins ending with a numeral ranging from 0 to 9 and the password needed to use them.

Using this information:
# Connect to the SFTP server using your SFTP login and password, through your favourite SFTP client software (such as WinSCP for example)
# Check than in your home folder you have:
#* One folder for each of the three example games (reversi, hearts, gomoku)
#* One folder matching the game you will be developing
#* One 'resources.html' file
# Open the resources.html file, it contains
#* The URL pointing to the BGA Studio website (protected with an HTTP Basic authentication scheme, the login and password are also referenced in the 'resources.html' file
#* The URL pointing to the BGA Studio backoffice (please note that you must first be logged in on the BGA Studio website to be able to access the backoffice, as the authentication is shared between the two)
#* The URL pointing to the web administration tool for the BGA Studio database.
# Click on the URL to the BGA Studio website, enter the HTTP Basic credentials when prompted for them (and have your browser conveniently memorize them for you). Then you get to an home page just like the one of the main BGA website. Enter one of your ten BGA studio logins to connect as a user.

== Launch your game and check how to update it ==
# Find your game in the 'Play now' section and launch a table
# Use the 'I want between X and X' players to tick down the maximum players number to the minimum
# Click 'Express start': your game launches with the maximum number of players specified. It shows an empty canvas: in the game zone you just have a sentence 'This is your game interface. You can edit this HTML in your ".tpl" file.'.
# Switch to your SFTP home folder, go into your game folder. Edit the game_game.tpl file, and change this sentence to 'Hey, this is my first game!', then save.
# Go back to your browser and refresh, check that the game zone has updated.
# Click on the 'Exit game' icon on the top right, and in the popup choose 'Express game stop'. The game ends automatically and you are brought back to the table screen for this ended game.
# Switch to your game folder, go into the img folder and overwrite your game_box.png file with another image.
# Go back to your browser, '''empty your browser cache''', then refresh the page, and check that the game box image has been updated.

== Commit your changes ==

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

Here is how to go through your first commit:
# Go back to your browser tab showing the 'resources.html' file. Click on the URL pointing to the BGA Studio backoffice (do not log out of the BGA Studio website before doing so, or you will get a '''Not authorized''' error message as the authentication is shared);
# Click on the 'Sources' menu entry to show the commit form. Enter your game name (under the same form as the name of your game folder: lowercase, no spaces), enter your commit comment (such as 'My first commit') then hit the 'Submit' button;
# Check the log for errors, it should end with the following lines:

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

NB: you should also commit each time you make an change to your gameoptions.inc.php file or to your stats.inc.php file, as an extra deployment action is needed from us for these files to take effect. Please mention in your commit comment that you need us to deploy those files, or send us an email to ask us to do it.

== That's all for your first steps! ==

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

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

Studio

2013-04-13T13:38:56Z

Een:

[[File:Bga_studio_small.jpg]]

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

== What is Board Game Arena Studio? ==

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

It is open to any gamer with development skills :)

See announcement here:
http://forum.boardgamearena.com/viewtopic.php?f=10&t=1973

== Discover BGA Studio in 5 presentations ==

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

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

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

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

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

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

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

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

Then start editing files and see what happens! ;)

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

== BGA Studio documentation ==

=== BGA Studio Framework reference ===

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

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

==== Game logic ====

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

==== Game interface ====

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

==== Other components ====

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

=== BGA Studio game components reference ===

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

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

=== BGA Studio user guide ===

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

* [[Tools and tips of BGA Studio]]

* [[Practical debugging]]

* [[Studio back-office]]

* [[Studio FAQ]]

== Other resources ==

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

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

Studio

2013-04-13T13:38:25Z

Een: /* BGA Studio user guide */

[[File:Bga_studio_small.jpg]]

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

== What is Board Game Arena Studio? ==

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

It is open to any gamer with development skills :)

See announcement here:
http://forum.boardgamearena.com/viewtopic.php?f=10&t=1973

== Discover BGA Studio in 5 presentations ==

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

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

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

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

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

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

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

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

Then start editing files and see what happens! ;)

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

== BGA Studio documentation ==

=== BGA Studio Framework reference ===

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

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

==== Game logic ====

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

==== Game interface ====

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

==== Other components ====

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

=== BGA Studio game components reference ===

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

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

=== BGA Studio user guide ===

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

* [[Tools and tips of BGA Studio]]

* [[Practical debugging]]

* [[Studio back-office]]

* [[Studio FAQ]]

== Other resources ==

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

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

Studio

2013-04-13T13:38:01Z

Een: /* BGA Studio documentation */

[[File:Bga_studio_small.jpg]]

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

== What is Board Game Arena Studio? ==

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

It is open to any gamer with development skills :)

See announcement here:
http://forum.boardgamearena.com/viewtopic.php?f=10&t=1973

== Discover BGA Studio in 5 presentations ==

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

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

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

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

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

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

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

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

Then start editing files and see what happens! ;)

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

== BGA Studio documentation ==

=== BGA Studio Framework reference ===

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

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

==== Game logic ====

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

==== Game interface ====

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

==== Other components ====

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

=== BGA Studio game components reference ===

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

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

== BGA Studio user guide ==

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

* [[Tools and tips of BGA Studio]]

* [[Practical debugging]]

* [[Studio back-office]]

* [[Studio FAQ]]

== Other resources ==

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

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

First steps with BGA Studio

2013-04-13T13:11:19Z

Een: Created page with "== Connect to your SFTP folder and to the BGA Studio website == After your account has been created, you will get by email: * the name of the SFTP server to connect to * you..."

Studio

2013-04-13T12:36:20Z

Een: /* BGA Studio user guide */

[[File:Bga_studio_small.jpg]]

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

== What is Board Game Arena Studio? ==

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

It is open to any gamer with development skills :)

See announcement here:
http://forum.boardgamearena.com/viewtopic.php?f=10&t=1973

== Discover BGA Studio in 5 presentations ==

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

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

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

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

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

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

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

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

Then start editing files and see what happens! ;)

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

== BGA Studio documentation ==

=== BGA Studio Framework reference ===

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

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

==== Game logic ====

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

==== Game interface ====

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

==== Other components ====

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

=== BGA Studio game components reference ===

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

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

== BGA Studio user guide ==

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

* [[Tools and tips of BGA Studio]]

* [[Practical debugging]]

* [[Studio back-office]]

* [[Studio FAQ]]

== Other resources ==

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

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

Studio

2013-04-13T12:35:51Z

Een: /* BGA Studio user guide */

[[File:Bga_studio_small.jpg]]

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

== What is Board Game Arena Studio? ==

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

It is open to any gamer with development skills :)

See announcement here:
http://forum.boardgamearena.com/viewtopic.php?f=10&t=1973

== Discover BGA Studio in 5 presentations ==

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

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

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

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

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

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

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

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

Then start editing files and see what happens! ;)

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

== BGA Studio documentation ==

=== BGA Studio Framework reference ===

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

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

==== Game logic ====

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

==== Game interface ====

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

==== Other components ====

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

=== BGA Studio game components reference ===

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

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

== BGA Studio user guide ==

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

[[Tools and tips of BGA Studio]]

[[Practical debugging]]

[[Studio back-office]]

[[Studio FAQ]]

== Other resources ==

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

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