Board Game Arena - User contributions [en]

Tips hex

2023-02-25T15:21:29Z

User Already Exists: /* Experts and beyond */ updated wording

== Overview ==

Although the rules of Hex are very simple, its strategy is quite rich and has many layers. The good news is that there are many clever and satisfying strategy concepts that can be learned by players of all levels.

== Strategy concepts by level ==

The following is an approximate attempt to match up strategy skills with Elo levels.

=== Beginners ===

To reach level 100, you should learn about templates, especially the [https://www.hexwiki.net/index.php/Bridge bridge] and the [https://www.hexwiki.net/index.php/Ziggurat ziggurat]. You should also learn basic [https://www.hexwiki.net/index.php/Blocking blocking]. You might try a few dozen of Matthew Seymour's [http://www.mseymour.ca/hex_puzzle/ Hex puzzles].

=== Average players ===

To reach level 200, you should learn about [https://www.hexwiki.net/index.php/Ladder_handling ladder handling], especially [https://www.hexwiki.net/index.php/Ladder_escape ladder escapes]. You should learn more [https://www.hexwiki.net/index.php/Edge_templates_everybody_should_know templates]. You should solve more [http://www.mseymour.ca/hex_puzzle/ Hex puzzles].

=== Good players ===

To reach level 300, you should learn about [https://www.hexwiki.net/index.php/Climbing pivoting and climbing]. You should use template intrusions to steal territory and help you connect. You should recognize what is connected and what is not, to avoid defending the indefensible or attacking what is solid. You should also learn [https://www.hexwiki.net/index.php/Swap when to swap].

=== Strong players ===

To reach level 400, you should learn some advanced ways of connecting, such as [https://www.hexwiki.net/index.php/Switchback switchbacks], [https://www.hexwiki.net/index.php/Foldback foldbacks], and [https://www.hexwiki.net/index.php/Tom%27s_move Tom's move]. You should learn to [https://www.hexwiki.net/index.php/Foiling foil], and especially, how to counter fishing moves. You should start to use [https://www.hexwiki.net/index.php/Minimax minimaxing], such as building [https://www.hexwiki.net/index.php/Wall walls]. You should play [https://www.hexwiki.net/index.php/Corner_move corner moves] in the opening.

To reach level 500, you should consistently use [https://www.hexwiki.net/index.php/Minimax minimaxing], choosing from among several possible moves to gain small advantages. You should play [https://www.hexwiki.net/index.php/Tidiness tidily]. You should know when to respond locally and when to play elsewhere. You should learn more theory, such as the [https://www.hexwiki.net/index.php/Mustplay_region mustplay region] and [https://www.hexwiki.net/index.php/Ladder_creation_template ladder creation templates]. You should play [https://www.hexwiki.net/index.php/Joseki josekis].

=== Experts and beyond ===

To reach level 600, you should study different [https://www.hexwiki.net/index.php/Opening openings] and the best responses to them. You should know how to use [https://www.hexwiki.net/index.php/Flank flanks] and [https://www.hexwiki.net/index.php/Pivoting_template pivoting templates]. You should learn about [https://www.hexwiki.net/index.php/Captured_cell capture] and [https://www.hexwiki.net/index.php/Dominated_cell domination] to play locally optimal moves.

To go beyond level 600, you no longer need this strategy guide. Read the [https://www.hexwiki.net HexWiki]. Learn from players who are better than you. Play a lot and watch a lot of games. Develop your own tactics.

== Resources ==

* Matthew Seymour's online book [http://www.mseymour.ca/hex_book/ Hex: A Strategy Guide]. A good starting point for learning Hex strategy.

* Matthew Seymour's [http://www.mseymour.ca/hex_puzzle/ Hex puzzles]. Fun and very addictive! You will become a better player.

* The [https://www.hexwiki.net/ HexWiki]. Too much information for beginners, as it is difficult to know what to read first. It is better to start with Seymour's book. However, the Wiki is a great resource once you've mastered the basics.

Stock

2023-02-14T00:35:32Z

User Already Exists: /* Using stock: a simple example */ typo

{{Studio_Framework_Navigation}}

== Overview ==

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

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

Examples of stock use cases:

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

Using stock:

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

== Using stock: a simple example ==

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

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

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

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

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

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

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

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

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

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

Explanation:

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

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

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

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

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

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

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

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

== Complete stock component reference ==

for interest, the source is available here : https://x.boardgamearena.net/data/themereleases/220811-1000/js/modules/stock.js (this link may change with new release)

In the reference below the type StockItem refers to a record { id: number, type: number }, i.e. {id: 22, type: 3}

And StockItemType is record {weight: number, image: string, image_position: number}

=== Creation ===

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

With create, you create a new stock component.

Parameters:
* page: the container page. Usually: "this".
* container_div: the container "div" element. Its not an id, if you have id you can pass $(id). It must exists.
* width and height (in pixels) for the stock component.

(See ''Hearts'' example above).

'''addItemType(type: number, weight: number, image: string, image_position: number ): void'''

Define a new type of item (StockItemtType) and add it to the stock with given type id.

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

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

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

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

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

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

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

=== Add/Remove items ===

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

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

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

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

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

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

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

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

This is especially useful:

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

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

Remove an item of the specific type from the stock.

'to' is an optional parameter. If "to" contains the ID of an HTML element, the item removed from the Stock slides to this HTML element before it disappears. Note that this method does not expose the associated animation object, however, so it's not possible to trigger other actions when it finishes, for example. If you need to do that, use Dojo's slideToObject() instead.

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

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

Remove an item with a specific ID from the stock.

'to' is an optional parameter. If "to" contains the ID of an HTML element, the item removed from the Stock slides to this HTML element before it disappears. Note that this method does not expose the associated animation object, however, so it's not possible to trigger other actions when it finishes, for example. If you need to do that, use Dojo's slideToObject() instead.

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

'''removeAll()'''

Remove all items from the stock.

'''removeAllTo( to )'''

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

=== Getters ===

'''getPresentTypeList()'''

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

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

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

'''count():'''

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

'''getAllItems()'''

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

'''getItemDivId(id)'''

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

'''getItemById(id)'''

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

'''getItemWeightById(id: number): number|null'''

Returns item weigh given id. or null if not found

'''container_div'''

Member containing div of the stock container in dom (container_div.id would be it's id)

'''control_name'''
Its id of container_div above

=== Selection ===

'''setSelectionMode( mode )'''

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

'''setSelectionAppearance( type )'''

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

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

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

'''isSelected( id )'''

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

'''selectItem( id )'''

Select the specified item.

'''unselectItem( id )'''

Unselect the specified item.

'''unselectAll()'''

Unselect all items of the stock.

'''selectItemsByType(type: number): void'''

Selectes all items in a stock with given type (in addition to previous selection)

'''unselectItemsByType(type: number): void'''

Unselects all items in a stock with given type

'''onChangeSelection'''

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

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

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

(...)

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

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

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

'''getSelectedItems()'''

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

'''getUnselectedItems()'''

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

=== Layout ===

'''resetItemsPosition()'''

If you moved an item from the stock control manually (ex: after a drag'n'drop) and want to reset their positions to their original ones, you can call this method.
Note: it is the same as updateDisplay() without arugment, not sure why there are two methods.

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

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

'''item_margin'''

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

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

'''changeItemsWeight( newWeights )'''

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

Items are immediately re-sorted with the new weight.

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

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

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

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

'''centerItems'''

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

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

This functions sents stock horizontal_overlap and vertical_overlap, the calls updateDisplay(). See what overlap means below

'''horizontal_overlap'''

Make items of the stock control "overlap" each other, to save space. By default, horizontal_overlap is 0 (but there is also '''item_margin''' which affects spacing''')'''.

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

'''vertical_overlap'''

There is two modes, in one mode it used to adjust every 2nd item (See the games "Jaipur" or "Koryŏ"), second mode when setting use_vertical_overlap_as_offset=false is more/less normal overlap with vertical layout except its perentage of overlap (opposite of horizontal_overlap).

This is example of vertical stock with overlap
<pre>
stock.container_div.width = "60px"; // enought just for 1 card
stock.autowidth = false; // this is required so it obeys the width set above
stock.use_vertical_overlap_as_offset = false; // this is to use normal vertical_overlap
stock.vertical_overlap = 20; // overlap
stock.horizontal_overlap = -1; // current bug in stock - this is needed to enable z-index on overlapping items
stock.item_margin = 0; // has to be 0 if using overlap
stock.updateDisplay(); // re-layout
</pre>
[[File:StockV.png]] [[File:StockHV.png]] [[File:StockMixed.png]]

'''autowidth'''

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

'''resizeItems( width, height, background_width, background_height )'''

background_width is an optional argument.

background_height is an optional argument.

<pre> stock.resizeItems(100, 120, 150, 170);</pre>

=== Customize Appearance ===

'''extraClasses'''

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

this.playerHand.extraClasses='mycard';

Note that it is the same list for all items.

'''onItemCreate'''

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

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

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

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

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

</pre>

'''onItemDelete'''

Function handler called when div is removed

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

'''jstpl_stock_item'''

Override default HTML template, this is the default:
<pre>
mystock.jstpl_stock_item ='<div id="${id}" class="stockitem ${extra_classes}" style="top:${top}px;left:${left}px;width:${width}px;height:${height}px;${position};background-image:url(\'${image}\');${additional_style}"></div>';

</pre>

Note: variable ${position} normally resolve to nothing or z-index: X - depending on overlap variables, and additional_style resolves to `background-size: ${this.backgroundSize}` if it is set

'''custom CSS images'''

If you want to use your own css styles for images on the items (i.e. not grid), you can do it as following, use customize template, then modify onItemCreate to add slyle which is based on type

<pre>
mystock.jstpl_stock_item = '<div id="${id}" class="stockitem card" style="top:${top}px;left:${left}px;${position};"></div>';
mystock.onItemCreate = (card_div, card_type_id, card_id ) => { dojo.addClass(card_div, 'card_type_'+card_type_id); }
for (var type = 0; type <= 48; type++) {
mystock.addItemType(type, type); // we skipped image and image position here
}
</pre>

Note: in this case your CSS must define all styles require for these stock items such as width, heigh, image and image positioning for every type

<pre>
.card {
width: 50px;
height: 80px;
background-image: url(img/cards.jpg);
background-size: 600% auto;
}
.card_type_1 {
background-postion: 20% 0%;
}
</pre>

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

Most cases will be one of the following situations:

'''Situation A''':

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

* Use '''addToStockWithId''' with a "from" argument set to the element of your interface where the card should come from (i.e. div id). For example if you want to "reveal" card from player hand and it is not an interface element you can set from to be 'player_board_'+activePlayerId (where activePlayerId is player who played that card).

'''Situation B''':

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

* On the destination Stock, use '''addToStockWithId''' with a "from" argument which is the HTML id of the corresponding item in the source Stock. For example, if the source stock id is "myHand", then the HTML id of card 48 is "myHand_item_48".
* Then, remove the source item with '''removeFromStockById'''. Note: do NOT set the 'to' argument in this call, otherwise you'll get two animations.

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

'''Situation C''':

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

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

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

== Known issues ==

==== Incorrectly displayed sprites on Safari ====

As mentioned above, stock displays its images using "sprites" consisting of a portion of a larger image. To accomplish this, it uses the CSS background-position attribute in negative multiples of 100%. For example, the first element of the first row would be 0% 0%. The second element of the first row would be -100% 0%, etc.

This works fine except in Safari, which sometimes slightly modifies the width of elements at smaller screen sizes (usually when minimum width of 'game_interface_width' is not null) in game. For example, you might get a ~49.99px x ~49.99px div instead of the 50px x 50px specified by CSS width/height. Combined with using percentages in background-position, this can cause sprites to be slightly off-center.

Using pixels in background-position is probably the easiest way to fix this problem, but that would require modifying the stock code itself. As a developer, you can also work around the problem by specifying a background-size attribute based on the size in elements of your source image. For example, if you have a source image that contains 5 rows of 28 sprites, you should specify "background-size: 2800% 500%;"

You can add background-size to your stock items by using the extraClasses attribute as explained above and then specifying the values in your game.css file.

[[Category:Studio]]

Tips hex

2022-09-19T17:03:33Z

User Already Exists: /* Experts and beyond */ wording

== Overview ==

Although the rules of Hex are very simple, its strategy is quite rich and has many layers. The good news is that there are many clever and satisfying strategy concepts that can be learned by players of all levels.

== Strategy concepts by level ==

The following is an approximate attempt to match up strategy skills with Elo levels.

=== Beginners ===

To reach level 100, you should learn about templates, especially the [https://www.hexwiki.net/index.php/Bridge bridge] and the [https://www.hexwiki.net/index.php/Ziggurat ziggurat]. You should also learn basic [https://www.hexwiki.net/index.php/Blocking blocking]. You might try a few dozen of Matthew Seymour's [http://www.mseymour.ca/hex_puzzle/ Hex puzzles].

=== Average players ===

To reach level 200, you should learn about [https://www.hexwiki.net/index.php/Ladder_handling ladder handling], especially [https://www.hexwiki.net/index.php/Ladder_escape ladder escapes]. You should learn more [https://www.hexwiki.net/index.php/Edge_templates_everybody_should_know templates]. You should solve more [http://www.mseymour.ca/hex_puzzle/ Hex puzzles].

=== Good players ===

To reach level 300, you should learn about [https://www.hexwiki.net/index.php/Climbing pivoting and climbing]. You should use template intrusions to steal territory and help you connect. You should recognize what is connected and what is not, to avoid defending the indefensible or attacking what is solid. You should also learn [https://www.hexwiki.net/index.php/Swap when to swap].

=== Strong players ===

To reach level 400, you should learn some advanced ways of connecting, such as [https://www.hexwiki.net/index.php/Switchback switchbacks], [https://www.hexwiki.net/index.php/Foldback foldbacks], and [https://www.hexwiki.net/index.php/Tom%27s_move Tom's move]. You should learn to [https://www.hexwiki.net/index.php/Foiling foil], and especially, how to counter fishing moves. You should start to use [https://www.hexwiki.net/index.php/Minimax minimaxing], such as building [https://www.hexwiki.net/index.php/Wall walls]. You should play [https://www.hexwiki.net/index.php/Corner_move corner moves] in the opening.

To reach level 500, you should consistently use [https://www.hexwiki.net/index.php/Minimax minimaxing], choosing from among several possible moves to gain small advantages. You should play [https://www.hexwiki.net/index.php/Tidiness tidily]. You should know when to respond locally and when to play elsewhere. You should learn more theory, such as the [https://www.hexwiki.net/index.php/Mustplay_region mustplay region] and [https://www.hexwiki.net/index.php/Ladder_creation_template ladder creation templates]. You should play [https://www.hexwiki.net/index.php/Joseki josekis].

=== Experts and beyond ===

To reach level 600, you should study different [https://www.hexwiki.net/index.php/Opening openings] and the best responses to them. You should know how to use [https://www.hexwiki.net/index.php/Flank flanks] and [https://www.hexwiki.net/index.php/Pivoting_template pivoting templates]. You should learn about [https://www.hexwiki.net/index.php/Captured_cell capture] and [https://www.hexwiki.net/index.php/Dominated_cell domination] to play locally optimal moves.

To go beyond level 600, you no longer need this strategy guide. Read the [https://www.hexwiki.net HexWiki]. Learn from players who are better than you. Play a lot and watch a lot of games. Develop your own theories.

== Resources ==

* Matthew Seymour's online book [http://www.mseymour.ca/hex_book/ Hex: A Strategy Guide]. A good starting point for learning Hex strategy.

* Matthew Seymour's [http://www.mseymour.ca/hex_puzzle/ Hex puzzles]. Fun and very addictive! You will become a better player.

* The [https://www.hexwiki.net/ HexWiki]. Too much information for beginners, as it is difficult to know what to read first. It is better to start with Seymour's book. However, the Wiki is a great resource once you've mastered the basics.

Gamehelphex

2022-07-31T21:00:19Z

User Already Exists: Copy-edited the introductory paragraph.

The game of Hex was invented by Piet Hein in Denmark in 1942, and later rediscovered and popularized by John Nash. The game is attractive because it has extremely simple rules, yet a surprising amount of strategic depth. Other interesting aspects are that the game can't end in a tie, and that when playing without the swap rule, the first player is known to have a theoretical winning strategy, although nobody knows what that strategy is.

== Rules ==

=== Goal ===

The board has two red edges and two blue edges. Each player's goal is to connect their two edges by stones of their color.

=== Turns ===

The players alternately place a stone of their own color on the board, with Red going first. A stone can be placed on any empty cell. Once placed, stones are never moved or removed.

=== The swap rule ===

To make sure the first player does not have an unfair advantage, the swap rule is used. After the first player opens with a red stone, the second player has the option to "swap", or steal the opponent's first move. In this case, Red's initial stone is replaced by a blue stone and mirrored about the long diagonal. After this, it is Red's turn.

=== Game end ===

The game ends when one of the players has connected their edges with a path of stones of their color. The game can't end in a tie. When it is clear to both players who will win, it is customary for the losing player to resign.

== Game options and interface ==

=== Board size ===

The game can be played on boards of several different sizes. The 6x6 board is designed to help beginners understand the basic rules and discover simple game patterns. The 11x11 board is a more classic size and was used by Piet Hein. The 12x12 board was added because some players like even-sized boards. The 13x13 board is preferred by many experts. The 14x14 board was recommended by John Nash, and the 15x15 board allows even longer plays.

The 6x6 board size is only available in training mode.

=== Moves and swapping ===

To make a move, click on an empty cell. To guard against accidental misclicks, you have to confirm each move by clicking on the stone a second time (or use the "confirm" or "cancel" buttons above the play area).

On the second move of the game, you have the option to swap. To do so, click on the "swap" button above the play area. If you do not want to swap, simply make a normal move.

=== Resigning ===

Players can resign at any time (whether or not it is their turn). The resign button is found in the "additional game controls" menu, which is marked by three dots "..." in the upper right corner of the play area.

=== Passing ===

Passing (i.e., skipping a move) is rarely done in Hex. The reason is that passing never benefits a player: if you can win by passing, you can also win by making a random move. Nevertheless, the ability to pass has been included in the Board Game Arena implementation of Hex. It has certain specialized uses, such as teaching, giving handicap (i.e., giving an advantage to the weaker player), or setting up an initial board position.

The option to pass is found in the "additional game controls" menu, which is marked by three dots "..." in the upper right corner of the play area. If your opponent passes and you do not want to allow it for some reason, simply pass yourself, which effectively returns the game to its previous state. Three passes in a row are not permitted, so if both players have passed, the next player must make a proper move.

=== Accessibility ===

The shades of red and blue that Hex uses by default can be difficult to distinguish for colorblind people. To compensate for this, there is a game display option for color blindness in the Options menu below the game board.

Gamehelphex

2022-07-30T02:06:26Z

User Already Exists: Added 12x12

The game of Hex was invented and popularized in Denmark by Piet Hein in 1942, and later independently rediscovered by John Nash in 1947. The game is attractive because it has extremely simple rules, yet a surprising amount of strategic depth. Another interesting aspect is that the game can't end in a tie.

== Rules ==

=== Goal ===

The board has two red edges and two blue edges. Each player's goal is to connect their two edges by stones of their color.

=== Turns ===

The players alternately place a stone of their own color on the board, with Red going first. A stone can be placed on any empty cell. Once placed, stones are never moved or removed.

=== The swap rule ===

To make sure the first player does not have an unfair advantage, the swap rule is used. After the first player opens with a red stone, the second player has the option to "swap", or steal the opponent's first move. In this case, Red's initial stone is replaced by a blue stone and mirrored about the long diagonal. After this, it is Red's turn.

=== Game end ===

The game ends when one of the players has connected their edges with a path of stones of their color. The game can't end in a tie. When it is clear to both players who will win, it is customary for the losing player to resign.

== Game options and interface ==

=== Board size ===

The game can be played on boards of several different sizes. The 6x6 board is designed to help beginners understand the basic rules and discover simple game patterns. The 11x11 board is a more classic size and was used by Piet Hein. The 12x12 board was added because some players like even-sized boards. The 13x13 board is preferred by many experts. The 14x14 board was recommended by John Nash, and the 15x15 board allows even longer plays.

The 6x6 board size is only available in training mode.

=== Moves and swapping ===

To make a move, click on an empty cell. To guard against accidental misclicks, you have to confirm each move by clicking on the stone a second time (or use the "confirm" or "cancel" buttons above the play area).

On the second move of the game, you have the option to swap. To do so, click on the "swap" button above the play area. If you do not want to swap, simply make a normal move.

=== Resigning ===

Players can resign at any time (whether or not it is their turn). The resign button is found in the "additional game controls" menu, which is marked by three dots "..." in the upper right corner of the play area.

=== Passing ===

Passing (i.e., skipping a move) is rarely done in Hex. The reason is that passing never benefits a player: if you can win by passing, you can also win by making a random move. Nevertheless, the ability to pass has been included in the Board Game Arena implementation of Hex. It has certain specialized uses, such as teaching, giving handicap (i.e., giving an advantage to the weaker player), or setting up an initial board position.

The option to pass is found in the "additional game controls" menu, which is marked by three dots "..." in the upper right corner of the play area. If your opponent passes and you do not want to allow it for some reason, simply pass yourself, which effectively returns the game to its previous state. Three passes in a row are not permitted, so if both players have passed, the next player must make a proper move.

=== Accessibility ===

The shades of red and blue that Hex uses by default can be difficult to distinguish for colorblind people. To compensate for this, there is a game display option for color blindness in the Options menu below the game board.

Gamehelphex

2022-03-22T02:51:35Z

User Already Exists: /* Accessibility */ Removed "now", since that option has been there for several months.

The game of Hex was invented and popularized in Denmark by Piet Hein in 1942, and later independently rediscovered by John Nash in 1947. The game is attractive because it has extremely simple rules, yet a surprising amount of strategic depth. Another interesting aspect is that the game can't end in a tie.

== Rules ==

=== Goal ===

The board has two red edges and two blue edges. Each player's goal is to connect their two edges by stones of their color.

=== Turns ===

The players alternately place a stone of their own color on the board, with Red going first. A stone can be placed on any empty cell. Once placed, stones are never moved or removed.

=== The swap rule ===

To make sure the first player does not have an unfair advantage, the swap rule is used. After the first player opens with a red stone, the second player has the option to "swap", or steal the opponent's first move. In this case, Red's initial stone is replaced by a blue stone and mirrored about the long diagonal. After this, it is Red's turn.

=== Game end ===

The game ends when one of the players has connected their edges with a path of stones of their color. The game can't end in a tie. When it is clear to both players who will win, it is customary for the losing player to resign.

== Game options and interface ==

=== Board size ===

The game can be played on boards of several different sizes. The 6x6 board is designed to help beginners understand the basic rules and discover simple game patterns. The 11x11 board is a more classic size and was used by Piet Hein. The 13x13 board is preferred by many experts. The 14x14 board was recommended by John Nash, and the 15x15 board allows even longer plays.

The 6x6 board size is only available in training mode.

=== Moves and swapping ===

To make a move, click on an empty cell. To guard against accidental misclicks, you have to confirm each move by clicking on the stone a second time (or use the "confirm" or "cancel" buttons above the play area).

On the second move of the game, you have the option to swap. To do so, click on the "swap" button above the play area. If you do not want to swap, simply make a normal move.

=== Resigning ===

Players can resign at any time (whether or not it is their turn). The resign button is found in the "additional game controls" menu, which is marked by three dots "..." in the upper right corner of the play area.

=== Passing ===

Passing (i.e., skipping a move) is rarely done in Hex. The reason is that passing never benefits a player: if you can win by passing, you can also win by making a random move. Nevertheless, the ability to pass has been included in the Board Game Arena implementation of Hex. It has certain specialized uses, such as teaching, giving handicap (i.e., giving an advantage to the weaker player), or setting up an initial board position.

The option to pass is found in the "additional game controls" menu, which is marked by three dots "..." in the upper right corner of the play area. If your opponent passes and you do not want to allow it for some reason, simply pass yourself, which effectively returns the game to its previous state. Three passes in a row are not permitted, so if both players have passed, the next player must make a proper move.

=== Accessibility ===

The shades of red and blue that Hex uses by default can be difficult to distinguish for colorblind people. To compensate for this, there is a game display option for color blindness in the Options menu below the game board.

Tips hex

2022-03-02T22:48:49Z

User Already Exists: Minor wording

== Overview ==

Although the rules of Hex are very simple, its strategy is quite rich and has many layers. The good news is that there are many clever and satisfying strategy concepts that can be learned by players of all levels.

== Strategy concepts by level ==

The following is an approximate attempt to match up strategy skills with Elo levels.

=== Beginners ===

To reach level 100, you should learn about templates, especially the [https://www.hexwiki.net/index.php/Bridge bridge] and the [https://www.hexwiki.net/index.php/Ziggurat ziggurat]. You should also learn basic [https://www.hexwiki.net/index.php/Blocking blocking]. You might try a few dozen of Matthew Seymour's [http://www.mseymour.ca/hex_puzzle/ Hex puzzles].

=== Average players ===

To reach level 200, you should learn about [https://www.hexwiki.net/index.php/Ladder_handling ladder handling], especially [https://www.hexwiki.net/index.php/Ladder_escape ladder escapes]. You should learn more [https://www.hexwiki.net/index.php/Edge_templates_everybody_should_know templates]. You should solve more [http://www.mseymour.ca/hex_puzzle/ Hex puzzles].

=== Good players ===

To reach level 300, you should learn about [https://www.hexwiki.net/index.php/Climbing pivoting and climbing]. You should use template intrusions to steal territory and help you connect. You should recognize what is connected and what is not, to avoid defending the indefensible or attacking what is solid. You should also learn [https://www.hexwiki.net/index.php/Swap when to swap].

=== Strong players ===

To reach level 400, you should learn some advanced ways of connecting, such as [https://www.hexwiki.net/index.php/Switchback switchbacks], [https://www.hexwiki.net/index.php/Foldback foldbacks], and [https://www.hexwiki.net/index.php/Tom%27s_move Tom's move]. You should learn to [https://www.hexwiki.net/index.php/Foiling foil], and especially, how to counter fishing moves. You should start to use [https://www.hexwiki.net/index.php/Minimax minimaxing], such as building [https://www.hexwiki.net/index.php/Wall walls]. You should play [https://www.hexwiki.net/index.php/Corner_move corner moves] in the opening.

To reach level 500, you should consistently use [https://www.hexwiki.net/index.php/Minimax minimaxing], choosing from among several possible moves to gain small advantages. You should play [https://www.hexwiki.net/index.php/Tidiness tidily]. You should know when to respond locally and when to play elsewhere. You should learn more theory, such as the [https://www.hexwiki.net/index.php/Mustplay_region mustplay region] and [https://www.hexwiki.net/index.php/Ladder_creation_template ladder creation templates]. You should play [https://www.hexwiki.net/index.php/Joseki josekis].

=== Experts and beyond ===

To reach level 600, you should study different [https://www.hexwiki.net/index.php/Opening openings] and the best responses to them. You should know how to use [https://www.hexwiki.net/index.php/Flank flanks] and [https://www.hexwiki.net/index.php/Pivoting_template pivoting templates]. You should learn about [https://www.hexwiki.net/index.php/Captured_cell capture] and [https://www.hexwiki.net/index.php/Dominated_cell domination] to play locally optimal moves.

To go beyond level 600, you no longer need this strategy guide. Read the [https://www.hexwiki.net HexWiki]. Learn from players who are better than you. Play a lot and watch a lot of games. Develop your own theory.

== Resources ==

* Matthew Seymour's online book [http://www.mseymour.ca/hex_book/ Hex: A Strategy Guide]. A good starting point for learning Hex strategy.

* Matthew Seymour's [http://www.mseymour.ca/hex_puzzle/ Hex puzzles]. Fun and very addictive! You will become a better player.

* The [https://www.hexwiki.net/ HexWiki]. Too much information for beginners, as it is difficult to know what to read first. It is better to start with Seymour's book. However, the Wiki is a great resource once you've mastered the basics.

Tips hex

2022-02-27T13:23:46Z

User Already Exists: /* Strategy concepts by level */ Added disclaimer

== Overview ==

Although the rules of Hex are very simple, its strategy is quite rich and has many layers. The good news is that there are many clever and satisfying strategy concepts that can be learned by players of all levels.

== Strategy concepts by level ==

The following is an attempt to match up strategy skills with Elo levels. It is of course approximate.

=== Beginners ===

To reach level 100, you should learn about templates, especially the [https://www.hexwiki.net/index.php/Bridge bridge] and the [https://www.hexwiki.net/index.php/Ziggurat ziggurat]. You should also learn basic [https://www.hexwiki.net/index.php/Blocking blocking]. You might try a few dozen of Matthew Seymour's [http://www.mseymour.ca/hex_puzzle/ Hex puzzles].

=== Average players ===

To reach level 200, you should learn about [https://www.hexwiki.net/index.php/Ladder_handling ladder handling], especially [https://www.hexwiki.net/index.php/Ladder_escape ladder escapes]. You should learn more [https://www.hexwiki.net/index.php/Edge_templates_everybody_should_know templates]. You should solve more [http://www.mseymour.ca/hex_puzzle/ Hex puzzles].

=== Good players ===

To reach level 300, you should learn about [https://www.hexwiki.net/index.php/Climbing pivoting and climbing]. You should use template intrusions to steal territory and help you connect. You should recognize what is connected and what is not, to avoid defending the indefensible or attacking what is solid. You should also learn [https://www.hexwiki.net/index.php/Swap when to swap].

=== Strong players ===

To reach level 400, you should learn some advanced ways of connecting, such as [https://www.hexwiki.net/index.php/Switchback switchbacks], [https://www.hexwiki.net/index.php/Foldback foldbacks], and [https://www.hexwiki.net/index.php/Tom%27s_move Tom's move]. You should learn to [https://www.hexwiki.net/index.php/Foiling foil], and especially, how to counter fishing moves. You should start to use [https://www.hexwiki.net/index.php/Minimax minimaxing], such as building [https://www.hexwiki.net/index.php/Wall walls]. You should play [https://www.hexwiki.net/index.php/Corner_move corner moves] in the opening.

To reach level 500, you should consistently use [https://www.hexwiki.net/index.php/Minimax minimaxing], choosing from among several possible moves to gain small advantages. You should play [https://www.hexwiki.net/index.php/Tidiness tidily]. You should know when to respond locally and when to play elsewhere. You should learn more theory, such as the [https://www.hexwiki.net/index.php/Mustplay_region mustplay region] and [https://www.hexwiki.net/index.php/Ladder_creation_template ladder creation templates]. You should play [https://www.hexwiki.net/index.php/Joseki josekis].

=== Experts and beyond ===

To reach level 600, you should study different [https://www.hexwiki.net/index.php/Opening openings] and the best responses to them. You should know how to use [https://www.hexwiki.net/index.php/Flank flanks] and [https://www.hexwiki.net/index.php/Pivoting_template pivoting templates]. You should learn about [https://www.hexwiki.net/index.php/Captured_cell capture] and [https://www.hexwiki.net/index.php/Dominated_cell domination] to play locally optimal moves.

To go beyond level 600, you no longer need this strategy guide. Read the [https://www.hexwiki.net HexWiki]. Learn from players who are better than you. Play a lot and watch a lot of games. Develop your own theory.

== Resources ==

* Matthew Seymour's online book [http://www.mseymour.ca/hex_book/ Hex: A Strategy Guide]. A good starting point for learning Hex strategy.

* Matthew Seymour's [http://www.mseymour.ca/hex_puzzle/ Hex puzzles]. Fun and very addictive! You will become a better player.

* The [https://www.hexwiki.net/ HexWiki]. Too much information for beginners, as it is difficult to know what to read first. It is better to start with Seymour's book. However, the Wiki is a great resource once you've mastered the basics.

Tips hex

2022-02-27T02:20:09Z

User Already Exists: Re-calibrated the topics by level. Probably still not completely accurate

== Overview ==

Although the rules of Hex are very simple, its strategy is quite rich and has many layers. The good news is that there are many clever and satisfying strategy concepts that can be learned by players of all levels.

== Strategy concepts by level ==

=== Beginners ===

To reach level 100, you should learn about templates, especially the [https://www.hexwiki.net/index.php/Bridge bridge] and the [https://www.hexwiki.net/index.php/Ziggurat ziggurat]. You should also learn basic [https://www.hexwiki.net/index.php/Blocking blocking]. You might try a few dozen of Matthew Seymour's [http://www.mseymour.ca/hex_puzzle/ Hex puzzles].

=== Average players ===

To reach level 200, you should learn about [https://www.hexwiki.net/index.php/Ladder_handling ladder handling], especially [https://www.hexwiki.net/index.php/Ladder_escape ladder escapes]. You should learn more [https://www.hexwiki.net/index.php/Edge_templates_everybody_should_know templates]. You should solve more [http://www.mseymour.ca/hex_puzzle/ Hex puzzles].

=== Good players ===

To reach level 300, you should learn about [https://www.hexwiki.net/index.php/Climbing pivoting and climbing]. You should use template intrusions to steal territory and help you connect. You should recognize what is connected and what is not, to avoid defending the indefensible or attacking what is solid. You should also learn [https://www.hexwiki.net/index.php/Swap when to swap].

=== Strong players ===

To reach level 400, you should learn some advanced ways of connecting, such as [https://www.hexwiki.net/index.php/Switchback switchbacks], [https://www.hexwiki.net/index.php/Foldback foldbacks], and [https://www.hexwiki.net/index.php/Tom%27s_move Tom's move]. You should learn to [https://www.hexwiki.net/index.php/Foiling foil], and especially, how to counter fishing moves. You should start to use [https://www.hexwiki.net/index.php/Minimax minimaxing], such as building [https://www.hexwiki.net/index.php/Wall walls]. You should play [https://www.hexwiki.net/index.php/Corner_move corner moves] in the opening.

To reach level 500, you should consistently use [https://www.hexwiki.net/index.php/Minimax minimaxing], choosing from among several possible moves to gain small advantages. You should play [https://www.hexwiki.net/index.php/Tidiness tidily]. You should know when to respond locally and when to play elsewhere. You should learn more theory, such as the [https://www.hexwiki.net/index.php/Mustplay_region mustplay region] and [https://www.hexwiki.net/index.php/Ladder_creation_template ladder creation templates]. You should play [https://www.hexwiki.net/index.php/Joseki josekis].

=== Experts ===

To reach level 600, you should study different [https://www.hexwiki.net/index.php/Opening openings] and the best responses to them. You should know how to use [https://www.hexwiki.net/index.php/Flank flanks] and [https://www.hexwiki.net/index.php/Pivoting_template pivoting templates]. You should learn about [https://www.hexwiki.net/index.php/Captured_cell capture] and [https://www.hexwiki.net/index.php/Dominated_cell domination] to play locally optimal moves.

To go beyond level 600, you no longer need this strategy guide. Read the [https://www.hexwiki.net HexWiki]. Learn from players who are better than you. Play a lot and watch a lot of games. Develop your own theory.

== Resources ==

* Matthew Seymour's online book [http://www.mseymour.ca/hex_book/ Hex: A Strategy Guide]. A good starting point for learning Hex strategy.

* Matthew Seymour's [http://www.mseymour.ca/hex_puzzle/ Hex puzzles]. Fun and very addictive! You will become a better player.

* The [https://www.hexwiki.net/ HexWiki]. Too much information for beginners, as it is difficult to know what to read first. It is better to start with Seymour's book. However, the Wiki is a great resource once you've mastered the basics.

Tips hex

2022-02-24T19:09:07Z

User Already Exists: /* Good players */ Added foiling.

== Overview ==

Although the rules of Hex are very simple, its strategy is quite rich and has many layers. The good news is that there are many clever and satisfying strategy concepts that can be learned by players of all levels.

=== Beginners ===

To reach level 100, you should learn about templates, especially the [https://www.hexwiki.net/index.php/Bridge bridge] and the [https://www.hexwiki.net/index.php/Ziggurat ziggurat]. You should also learn basic [https://www.hexwiki.net/index.php/Blocking blocking]. You might try a few dozen of Matthew Seymour's [http://www.mseymour.ca/hex_puzzle/ Hex puzzles].

=== Average players ===

To reach level 200, you should learn about [https://www.hexwiki.net/index.php/Ladder_handling ladder handling], especially [https://www.hexwiki.net/index.php/Ladder_escape ladder escapes], and [https://www.hexwiki.net/index.php/Climbing pivoting and climbing]. You should learn more [https://www.hexwiki.net/index.php/Edge_templates_everybody_should_know templates]. You should also begin to use template intrusions to steal territory and help you connect. You should also learn [https://www.hexwiki.net/index.php/Swap when to swap]. You should solve more [http://www.mseymour.ca/hex_puzzle/ Hex puzzles].

=== Good players ===

To reach level 300, you should learn some advanced ways of connecting, such as [https://www.hexwiki.net/index.php/Tom%27s_move Tom's move], [https://www.hexwiki.net/index.php/Switchback switchbacks], and [https://www.hexwiki.net/index.php/Foldback foldbacks]. You should learn to [https://www.hexwiki.net/index.php/Foiling foil], and especially, how to counter fishing moves. You should learn about the [https://www.hexwiki.net/index.php/Mustplay_region mustplay region] and to recognize what is connected and what is not, to avoid defending the indefensible or attacking what is solid. You should start to use [https://www.hexwiki.net/index.php/Minimax minimaxing], such as building [https://www.hexwiki.net/index.php/Wall walls]. You should learn some [https://www.hexwiki.net/index.php/Ladder_creation_template ladder creation templates]. You should also start playing [https://www.hexwiki.net/index.php/Corner_move corner moves].

=== Strong players ===

To reach level 400, you should consistently use [https://www.hexwiki.net/index.php/Minimax minimaxing]. You should learn to choose from among several possible moves to gain small advantages. You should learn to [https://www.hexwiki.net/index.php/Tidiness tidy up]. You should play [https://www.hexwiki.net/index.php/Joseki josekis].

To reach level 500, you should study different [https://www.hexwiki.net/index.php/Opening openings] and the best responses to them. You should know about [https://www.hexwiki.net/index.php/Flank flanks] and [https://www.hexwiki.net/index.php/Pivoting_template pivoting templates]. You should learn about [https://www.hexwiki.net/index.php/Captured_cell capture] and [https://www.hexwiki.net/index.php/Dominated_cell domination] to play locally optimal moves.

=== Experts ===

To go beyond level 500, you no longer need this strategy guide. Read the [https://www.hexwiki.net HexWiki]. Learn from players who are better than you. Play a lot and watch a lot of games. Develop your own theory.

== Resources ==

* Matthew Seymour's online book [http://www.mseymour.ca/hex_book/ Hex: A Strategy Guide]. A good starting point for learning Hex strategy.

* Matthew Seymour's [http://www.mseymour.ca/hex_puzzle/ Hex puzzles]. Fun and very addictive! You will become a better player.

* The [https://www.hexwiki.net/ HexWiki]. Too much information for beginners, as it is difficult to know what to read first. It is better to start with Seymour's book. However, the Wiki is a great resource once you've mastered the basics.

Tips hex

2022-02-24T19:06:48Z

User Already Exists: Created a page with strategy tips (more like a collection of links).

== Overview ==

Although the rules of Hex are very simple, its strategy is quite rich and has many layers. The good news is that there are many clever and satisfying strategy concepts that can be learned by players of all levels.

=== Beginners ===

To reach level 100, you should learn about templates, especially the [https://www.hexwiki.net/index.php/Bridge bridge] and the [https://www.hexwiki.net/index.php/Ziggurat ziggurat]. You should also learn basic [https://www.hexwiki.net/index.php/Blocking blocking]. You might try a few dozen of Matthew Seymour's [http://www.mseymour.ca/hex_puzzle/ Hex puzzles].

=== Average players ===

To reach level 200, you should learn about [https://www.hexwiki.net/index.php/Ladder_handling ladder handling], especially [https://www.hexwiki.net/index.php/Ladder_escape ladder escapes], and [https://www.hexwiki.net/index.php/Climbing pivoting and climbing]. You should learn more [https://www.hexwiki.net/index.php/Edge_templates_everybody_should_know templates]. You should also begin to use template intrusions to steal territory and help you connect. You should also learn [https://www.hexwiki.net/index.php/Swap when to swap]. You should solve more [http://www.mseymour.ca/hex_puzzle/ Hex puzzles].

=== Good players ===

To reach level 300, you should learn some advanced ways of connecting, such as [https://www.hexwiki.net/index.php/Tom%27s_move Tom's move], [https://www.hexwiki.net/index.php/Switchback switchbacks], and [https://www.hexwiki.net/index.php/Foldback foldbacks]. You should learn about the [https://www.hexwiki.net/index.php/Mustplay_region mustplay region] and to recognize what is connected and what is not, to avoid defending the indefensible or attacking what is solid. You should start to use [https://www.hexwiki.net/index.php/Minimax minimaxing], such as building [https://www.hexwiki.net/index.php/Wall walls]. You should learn some [https://www.hexwiki.net/index.php/Ladder_creation_template ladder creation templates]. You should also start playing [https://www.hexwiki.net/index.php/Corner_move corner moves].

=== Strong players ===

To reach level 400, you should consistently use [https://www.hexwiki.net/index.php/Minimax minimaxing]. You should learn to choose from among several possible moves to gain small advantages. You should learn to [https://www.hexwiki.net/index.php/Tidiness tidy up]. You should play [https://www.hexwiki.net/index.php/Joseki josekis].

To reach level 500, you should study different [https://www.hexwiki.net/index.php/Opening openings] and the best responses to them. You should know about [https://www.hexwiki.net/index.php/Flank flanks] and [https://www.hexwiki.net/index.php/Pivoting_template pivoting templates]. You should learn about [https://www.hexwiki.net/index.php/Captured_cell capture] and [https://www.hexwiki.net/index.php/Dominated_cell domination] to play locally optimal moves.

=== Experts ===

To go beyond level 500, you no longer need this strategy guide. Read the [https://www.hexwiki.net HexWiki]. Learn from players who are better than you. Play a lot and watch a lot of games. Develop your own theory.

== Resources ==

* Matthew Seymour's online book [http://www.mseymour.ca/hex_book/ Hex: A Strategy Guide]. A good starting point for learning Hex strategy.

* Matthew Seymour's [http://www.mseymour.ca/hex_puzzle/ Hex puzzles]. Fun and very addictive! You will become a better player.

* The [https://www.hexwiki.net/ HexWiki]. Too much information for beginners, as it is difficult to know what to read first. It is better to start with Seymour's book. However, the Wiki is a great resource once you've mastered the basics.

Tips connectfour

2022-02-24T17:44:32Z

User Already Exists: Added more strategy hints

== The first moves ==

The best starting move for you is to place a piece right at the center. To counter this move, place your piece on top of it.

== Watch out for traps ==

A common trap is for your opponent to have two adjacent discs on the bottom row, with empty space on both sides. You must move on the bottom row directly next to your opponent's discs, or else your opponent will get 3 in a row with spaces on both sides, which you can no longer block.

Another common trap on the bottom row is when the opponent has two discs with one empty space between them, and empty spaces on both sides. You must move in the middle between the two discs, or directly next to one of them, or else your opponent will get 3 in a row that you can no longer block.

Another common trap is the shape that looks like a sideways "V", with one horizontal and one diagonal leg. Your opponent can make 4 in a row in two different ways, which you cannot block. You will lose unless you manage to connect four elsewhere first.

== Keep an eye on diagonals ==

One of the best strategies in this game is to look at all the pieces and evaluate multiple ways of connecting four pieces in a straight line. Remember that there are only three ways to do so: vertically (which is easy to see and block), horizontally, and diagonally. On the 6x7 board, all horizontal and diagonal lines require the center column, which is why it is so important to occupy the center.

Watch out for diagonals. Four pieces placed diagonally are the most common way in which people often win.

== Counting ==

Often the game comes down to counting: when there are a number of columns that you cannot move in without losing, then you are forced to fill up the remaining columns. If there are an even number of spaces in the remaining columns, then it will be your turn again when they are filled up, and you will lose (unless you manage to connect four while filling up those columns!).

When it comes to counting, spaces on the 1st, 3rd, and 5th row (from the bottom) generally favour Red, and spaces on the 2nd, 4th, and 6th row generally favour Yellow. Therefore, if you are Yellow, try to arrange your traps so that the last remaining spot is on an even row; if you are Red, try to do so with an odd row. This way, if the column in question is the last one to fill up, you will win.

Tips connectfour

2022-02-24T17:31:10Z

User Already Exists: Some punctuation, capitalization

The best starting move for you is to place a piece right at the center. To counter this move, place your piece on top of it. One of the best strategies in this game is to look at all the pieces and evaluate multiple ways of connecting four pieces in a straight line. Remember to watch out for diagonals. Four pieces placed diagonally are the most common way in which people often win.

Gamehelpconnectfour

2022-02-14T23:55:31Z

User Already Exists: Edited for language and clarity.

==Objective==
Connect Four is a two-player connection game. The objective is to connect four of your colored discs in a straight line while preventing your opponent from doing the same.

==Game play==
The players take turns dropping one colored disc from the top into a vertically suspended grid. The discs fall straight down, occupying the lowest available space within the column.

The game ends when one player forms a horizontal, vertical, or diagonal line of four of their own discs. If the entire board fills up before either player achieves four in a row, then the game ends in a tie.

==Board sizes==
Four board sizes (6x7, 8x9, 9x9, and 10x10) are available in the BGA implementation.

==Opening rule==
Two optional opening rules are implemented to eliminate first player advantage.

* Pie rule: After the first player's first move, the second player may switch colors.

* Swap rule: The first player places three discs - a red disc, a yellow disc, and another red disc. After the first 3 discs are placed, the second player may switch colors.

==Arena mode==
The 6x7 board size is unavailable in Arena mode because the game is too easily solved.

The opening rule is locked as the swap rule, to allow various opening moves to be played and to remove any potential first/second player advantage.

Currently (since Oct. 2021), the board size option rotates as the season passes (9x9 → 8x9 → 9x9 → 8x9 → ...).

Gurus, ''do not vote for a 6x7 board size or non-swap openings!''

Gamehelphex

2021-11-13T14:07:10Z

User Already Exists: /* Accessibility */ wording

The game of Hex was invented and popularized in Denmark by Piet Hein in 1942, and later independently rediscovered by John Nash in 1947. The game is attractive because it has extremely simple rules, yet a surprising amount of strategic depth. Another interesting aspect is that the game can't end in a tie.

== Rules ==

=== Goal ===

The board has two red edges and two blue edges. Each player's goal is to connect their two edges by stones of their color.

=== Turns ===

The players alternately place a stone of their own color on the board, with Red going first. A stone can be placed on any empty cell. Once placed, stones are never moved or removed.

=== The swap rule ===

To make sure the first player does not have an unfair advantage, the swap rule is used. After the first player opens with a red stone, the second player has the option to "swap", or steal the opponent's first move. In this case, Red's initial stone is replaced by a blue stone and mirrored about the long diagonal. After this, it is Red's turn.

=== Game end ===

The game ends when one of the players has connected their edges with a path of stones of their color. The game can't end in a tie. When it is clear to both players who will win, it is customary for the losing player to resign.

== Game options and interface ==

=== Board size ===

The game can be played on boards of several different sizes. The 6x6 board is designed to help beginners understand the basic rules and discover simple game patterns. The 11x11 board is a more classic size and was used by Piet Hein. The 13x13 board is preferred by many experts. The 14x14 board was recommended by John Nash, and the 15x15 board allows even longer plays.

The 6x6 board size is only available in training mode.

=== Moves and swapping ===

To make a move, click on an empty cell. To guard against accidental misclicks, you have to confirm each move by clicking on the stone a second time (or use the "confirm" or "cancel" buttons above the play area).

On the second move of the game, you have the option to swap. To do so, click on the "swap" button above the play area. If you do not want to swap, simply make a normal move.

=== Resigning ===

Players can resign at any time (whether or not it is their turn). The resign button is found in the "additional game controls" menu, which is marked by three dots "..." in the upper right corner of the play area.

=== Passing ===

Passing (i.e., skipping a move) is rarely done in Hex. The reason is that passing never benefits a player: if you can win by passing, you can also win by making a random move. Nevertheless, the ability to pass has been included in the Board Game Arena implementation of Hex. It has certain specialized uses, such as teaching, giving handicap (i.e., giving an advantage to the weaker player), or setting up an initial board position.

The option to pass is found in the "additional game controls" menu, which is marked by three dots "..." in the upper right corner of the play area. If your opponent passes and you do not want to allow it for some reason, simply pass yourself, which effectively returns the game to its previous state. Three passes in a row are not permitted, so if both players have passed, the next player must make a proper move.

=== Accessibility ===

The shades of red and blue that Hex uses by default can be difficult to distinguish for colorblind people. To compensate for this, there is now a game display option for color blindness in the Options menu below the game board.

Gamehelphex

2021-11-12T18:40:38Z

User Already Exists: /* Accessibility */ Removed limitation.

The game of Hex was invented and popularized in Denmark by Piet Hein in 1942, and later independently rediscovered by John Nash in 1947. The game is attractive because it has extremely simple rules, yet a surprising amount of strategic depth. Another interesting aspect is that the game can't end in a tie.

== Rules ==

=== Goal ===

The board has two red edges and two blue edges. Each player's goal is to connect their two edges by stones of their color.

=== Turns ===

The players alternately place a stone of their own color on the board, with Red going first. A stone can be placed on any empty cell. Once placed, stones are never moved or removed.

=== The swap rule ===

To make sure the first player does not have an unfair advantage, the swap rule is used. After the first player opens with a red stone, the second player has the option to "swap", or steal the opponent's first move. In this case, Red's initial stone is replaced by a blue stone and mirrored about the long diagonal. After this, it is Red's turn.

=== Game end ===

The game ends when one of the players has connected their edges with a path of stones of their color. The game can't end in a tie. When it is clear to both players who will win, it is customary for the losing player to resign.

== Game options and interface ==

=== Board size ===

The game can be played on boards of several different sizes. The 6x6 board is designed to help beginners understand the basic rules and discover simple game patterns. The 11x11 board is a more classic size and was used by Piet Hein. The 13x13 board is preferred by many experts. The 14x14 board was recommended by John Nash, and the 15x15 board allows even longer plays.

The 6x6 board size is only available in training mode.

=== Moves and swapping ===

To make a move, click on an empty cell. To guard against accidental misclicks, you have to confirm each move by clicking on the stone a second time (or use the "confirm" or "cancel" buttons above the play area).

On the second move of the game, you have the option to swap. To do so, click on the "swap" button above the play area. If you do not want to swap, simply make a normal move.

=== Resigning ===

Players can resign at any time (whether or not it is their turn). The resign button is found in the "additional game controls" menu, which is marked by three dots "..." in the upper right corner of the play area.

=== Passing ===

Passing (i.e., skipping a move) is rarely done in Hex. The reason is that passing never benefits a player: if you can win by passing, you can also win by making a random move. Nevertheless, the ability to pass has been included in the Board Game Arena implementation of Hex. It has certain specialized uses, such as teaching, giving handicap (i.e., giving an advantage to the weaker player), or setting up an initial board position.

The option to pass is found in the "additional game controls" menu, which is marked by three dots "..." in the upper right corner of the play area. If your opponent passes and you do not want to allow it for some reason, simply pass yourself, which effectively returns the game to its previous state. Three passes in a row are not permitted, so if both players have passed, the next player must make a proper move.

=== Accessibility ===

The shades of red and blue that Hex uses by default can be difficult to distinguish for colorblind people. To compensate for this, select Game Display: Color blindness in the Options menu below the game board.

Gamehelphex

2021-11-10T04:01:29Z

User Already Exists: /* Accessibility */

The game of Hex was invented and popularized in Denmark by Piet Hein in 1942, and later independently rediscovered by John Nash in 1947. The game is attractive because it has extremely simple rules, yet a surprising amount of strategic depth. Another interesting aspect is that the game can't end in a tie.

== Rules ==

=== Goal ===

The board has two red edges and two blue edges. Each player's goal is to connect their two edges by stones of their color.

=== Turns ===

The players alternately place a stone of their own color on the board, with Red going first. A stone can be placed on any empty cell. Once placed, stones are never moved or removed.

=== The swap rule ===

To make sure the first player does not have an unfair advantage, the swap rule is used. After the first player opens with a red stone, the second player has the option to "swap", or steal the opponent's first move. In this case, Red's initial stone is replaced by a blue stone and mirrored about the long diagonal. After this, it is Red's turn.

=== Game end ===

The game ends when one of the players has connected their edges with a path of stones of their color. The game can't end in a tie. When it is clear to both players who will win, it is customary for the losing player to resign.

== Game options and interface ==

=== Board size ===

The game can be played on boards of several different sizes. The 6x6 board is designed to help beginners understand the basic rules and discover simple game patterns. The 11x11 board is a more classic size and was used by Piet Hein. The 13x13 board is preferred by many experts. The 14x14 board was recommended by John Nash, and the 15x15 board allows even longer plays.

The 6x6 board size is only available in training mode.

=== Moves and swapping ===

To make a move, click on an empty cell. To guard against accidental misclicks, you have to confirm each move by clicking on the stone a second time (or use the "confirm" or "cancel" buttons above the play area).

On the second move of the game, you have the option to swap. To do so, click on the "swap" button above the play area. If you do not want to swap, simply make a normal move.

=== Resigning ===

Players can resign at any time (whether or not it is their turn). The resign button is found in the "additional game controls" menu, which is marked by three dots "..." in the upper right corner of the play area.

=== Passing ===

Passing (i.e., skipping a move) is rarely done in Hex. The reason is that passing never benefits a player: if you can win by passing, you can also win by making a random move. Nevertheless, the ability to pass has been included in the Board Game Arena implementation of Hex. It has certain specialized uses, such as teaching, giving handicap (i.e., giving an advantage to the weaker player), or setting up an initial board position.

The option to pass is found in the "additional game controls" menu, which is marked by three dots "..." in the upper right corner of the play area. If your opponent passes and you do not want to allow it for some reason, simply pass yourself, which effectively returns the game to its previous state. Three passes in a row are not permitted, so if both players have passed, the next player must make a proper move.

=== Accessibility ===

The shades of red and blue that Hex uses by default can be difficult to distinguish for colorblind people. To compensate for this, there is now a "Color blindness" setting in the "Options" below the game board. It changes the colors to be more easily distinguishable. (Limitation: this currently only works for games in progress, and not during replay).

Gamehelphex

2021-11-09T04:09:42Z

User Already Exists: /* Game options and interface */

The game of Hex was invented and popularized in Denmark by Piet Hein in 1942, and later independently rediscovered by John Nash in 1947. The game is attractive because it has extremely simple rules, yet a surprising amount of strategic depth. Another interesting aspect is that the game can't end in a tie.

== Rules ==

=== Goal ===

The board has two red edges and two blue edges. Each player's goal is to connect their two edges by stones of their color.

=== Turns ===

The players alternately place a stone of their own color on the board, with Red going first. A stone can be placed on any empty cell. Once placed, stones are never moved or removed.

=== The swap rule ===

To make sure the first player does not have an unfair advantage, the swap rule is used. After the first player opens with a red stone, the second player has the option to "swap", or steal the opponent's first move. In this case, Red's initial stone is replaced by a blue stone and mirrored about the long diagonal. After this, it is Red's turn.

=== Game end ===

The game ends when one of the players has connected their edges with a path of stones of their color. The game can't end in a tie. When it is clear to both players who will win, it is customary for the losing player to resign.

== Game options and interface ==

=== Board size ===

The game can be played on boards of several different sizes. The 6x6 board is designed to help beginners understand the basic rules and discover simple game patterns. The 11x11 board is a more classic size and was used by Piet Hein. The 13x13 board is preferred by many experts. The 14x14 board was recommended by John Nash, and the 15x15 board allows even longer plays.

The 6x6 board size is only available in training mode.

=== Moves and swapping ===

To make a move, click on an empty cell. To guard against accidental misclicks, you have to confirm each move by clicking on the stone a second time (or use the "confirm" or "cancel" buttons above the play area).

On the second move of the game, you have the option to swap. To do so, click on the "swap" button above the play area. If you do not want to swap, simply make a normal move.

=== Resigning ===

Players can resign at any time (whether or not it is their turn). The resign button is found in the "additional game controls" menu, which is marked by three dots "..." in the upper right corner of the play area.

=== Passing ===

Passing (i.e., skipping a move) is rarely done in Hex. The reason is that passing never benefits a player: if you can win by passing, you can also win by making a random move. Nevertheless, the ability to pass has been included in the Board Game Arena implementation of Hex. It has certain specialized uses, such as teaching, giving handicap (i.e., giving an advantage to the weaker player), or setting up an initial board position.

The option to pass is found in the "additional game controls" menu, which is marked by three dots "..." in the upper right corner of the play area. If your opponent passes and you do not want to allow it for some reason, simply pass yourself, which effectively returns the game to its previous state. Three passes in a row are not permitted, so if both players have passed, the next player must make a proper move.

=== Accessibility ===

The shades of red and blue that Hex uses by default can be difficult to distinguish for colorblind people. To fix this, go to the Preferences in the BGA menu in the upper right corner of the screen and change "Game display" to "Color blindness". (Limitation: this currently only works for games in progress, and not during replay).

Gamehelphex

2021-11-06T14:54:33Z

User Already Exists: Added a description of the game controls; copy-editing.

The game of Hex was invented and popularized in Denmark by Piet Hein in 1942, and later independently rediscovered by John Nash in 1947. The game is attractive because it has extremely simple rules, yet a surprising amount of strategic depth. Another interesting aspect is that the game can't end in a tie.

== Rules ==

=== Goal ===

The board has two red edges and two blue edges. Each player's goal is to connect their two edges by stones of their color.

=== Turns ===

The players alternately place a stone of their own color on the board, with Red going first. A stone can be placed on any empty cell. Once placed, stones are never moved or removed.

=== The swap rule ===

To make sure the first player does not have an unfair advantage, the swap rule is used. After the first player opens with a red stone, the second player has the option to "swap", or steal the opponent's first move. In this case, Red's initial stone is replaced by a blue stone and mirrored about the long diagonal. After this, it is Red's turn.

=== Game end ===

The game ends when one of the players has connected their edges with a path of stones of their color. The game can't end in a tie. When it is clear to both players who will win, it is customary for the losing player to resign.

== Game options and interface ==

=== Board size ===

The game can be played on boards of several different sizes. The 6x6 board is designed to help beginners understand the basic rules and discover simple game patterns. The 11x11 board is a more classic size and was used by Piet Hein. The 13x13 board is preferred by many experts. The 14x14 board was recommended by John Nash, and the 15x15 board allows even longer plays.

The 6x6 board size is only available in training mode.

=== Moves and swapping ===

To make a move, click on an empty cell. To guard against accidental misclicks, you have to confirm each move by clicking on the stone a second time (or use the "confirm" or "cancel" buttons above the play area).

On the second move of the game, you have the option to swap. To do so, click on the "swap" button above the play area. If you do not want to swap, simply make a normal move.

=== Resigning ===

Players can resign at any time (whether or not it is their turn). The resign button is found in the "additional game controls" menu, which is marked by three dots "..." in the upper right corner of the play area.

=== Passing ===

Passing (i.e., skipping a move) is rarely done in Hex. The reason is that passing never benefits a player: if you can win by passing, you can also win by making a random move. Nevertheless, the ability to pass has been included in the Board Game Arena implementation of Hex. It has certain specialized uses, such as teaching, giving handicap (i.e., giving an advantage to the weaker player), or setting up an initial board position.

The option to pass is found in the "additional game controls" menu, which is marked by three dots "..." in the upper right corner of the play area. If your opponent passes and you do not want to allow it for some reason, simply pass yourself, which effectively returns the game to its previous state. Three passes in a row are not permitted, so if both players have passed, the next player must make a proper move.

Gamehelphex

2021-11-04T12:20:34Z

User Already Exists: Updated rules for new release.

=== INTRODUCTION ===

The game of Hex was invented and popularized in Denmark by Piet Hein in 1942, and later independently rediscovered by John Nash in 1947. The game is attractive because it has extremely simple rules, yet a surprising amount of strategic depth. Another interesting aspect is that the game can't end in a tie.

=== GOAL ===

The board has two red edges and two blue edges. Each player's goal is to connect their two edges by stones of their color.

=== TURNS ===

The players alternately place a stone of their own color on the board, with Red going first. A stone can be placed on any empty cell. Once placed, stones are never moved or removed.

=== THE SWAP RULE ===

To make sure the first player does not have an unfair advantage, the swap rule is used. After the first player opens with a red stone, the second player can either
* continue to play normally, by placing a blue stone, or
* "swap", or steal the opponent's first move. In this case, Red's initial stone is replaced by a blue stone and mirrored about the long diagonal. After this, it is Red's turn.

=== GAME END ===

The game ends when one of the players has connected their edges with a path of stones of their color. The game can't end in a tie. It is customary for the losing player to resign when it is clear to both players who will win. The option to resign is in a menu indicated by three dots in the upper right corner of the play area.

=== BOARD SIZES ===

The game can be played on boards of several different sizes. The 6x6 board is designed to help beginners understand the basic rules and discover simple game patterns. The 11x11 board is a more classic size and was used by Piet Hein. The 13x13 board is preferred by many experts. The 14x14 board was recommended by John Nash, and the 15x15 board allows even longer plays.

The 6x6 board size is only available in training mode.

Gamehelphex

2021-06-15T23:11:34Z

User Already Exists: Minor copy-edits

=== INTRODUCTION ===

The game of Hex was invented and popularized in Denmark by Piet Hein in 1942, and later independently rediscovered by John Nash in 1947. The game is attractive because it has extremely simple rules, yet a surprising amount of strategic depth. Another interesting aspect is that the game can't end in a tie.

=== GOAL ===

The board has two red edges and two blue edges. Each player's goal is to connect their two edges by stones of their color.

=== TURNS ===

The players alternately place a stone of their own color on the board, with Red going first. A stone can be placed on any empty cell. Once placed, stones are never moved or removed.

=== THE SWAP RULE ===

To make sure the first player does not have an unfair advantage, the swap rule is used. After the first player opens with a red stone, the second player can either
* continue to play normally, by placing a blue stone, or
* decide to switch colors. In that case, the second player becomes Red, the first player becomes Blue, and the first move is kept. After this, the game continues normally, i.e., it is the first player's turn to play a blue stone.

Alternatively, the swap rule can also be implemented in such a way that the players keep their original colors. In that case, if Blue wants to swap, Red's initial stone is replaced by a blue stone and mirrored about the long diagonal. After this, it is Red's turn.

=== GAME END ===

The game ends when one of the players has connected their edges with a path of stones of their color. The game can't end in a tie. It is customary for the losing player to resign when it is clear to both players who will win.

=== BOARD SIZES ===

The game can be played on boards of several different sizes. The 6x6 board is designed to help beginners understand the basic rules and discover simple game patterns. The 11x11 board is a more classic size and was used by Piet Hein. The 13x13 board is preferred by many experts. The 14x14 board was recommended by John Nash, and the 15x15 board allows even longer plays.

Pre-release checklist

2021-06-06T06:26:07Z

User Already Exists: typo

{{Studio_Framework_Navigation}}

If you think your game is ready to be reviewed by by BGA admins and/or Publisher please consult this checklist first

* Metadata and graphics
** [[Game_meta-information: gameinfos.inc.php]] has correct and up to date information about the game
** Game box graphics is 3D version of the game box (if available) and publisher icon is correct (see [[Game art: img directory]]). Space around the box has to be transparent, not white.
** You have added a game_banner.jpg and some game_displayX.jpg images to make the game page pretty (NB: on the studio, you have to create a build for these images to appear on the studio game page)
** There are no images in the img directory that are not needed anymore
** Multiple images (i.e. cards) are compressed in "Sprite" (see [[Game art: img directory]])
** Each image should not exceed 4M
** Total size should not exceed 10M, image compression should be used otherwise
** If you use extra fonts, they should be freeware (please include a .txt with the licence information)
* Server side
** When giving their turn to a player, you give them some extra time with the giveExtraTime() function
** Game progression is implemented (getGameProgression() in php)
** Zombie turn is implemented (zombieTurn() in php). Note: it can only be tested if you explicitly click on the quit button to create a zombie. If you are expelled it does not generated a Zombie.
** You have defined and implemented some meaningful statistics for your game (i.e. total points, point from source A, B, C...)
** Game has meaningful notification messages (but don't overkill it, more user logs will slow down the loading)
** You implemented tiebreaking (using aux score field) and updated tiebreaker description in meta-data
* Client side
** Please check that you use ajaxcall only on player actions and never programmatically. Otherwise, your code will very likely create race conditions resulting in deadlocks or other errors.
* Special testing
** Game is tested with spectator (non player observer): change the testuser in the URL to see the game as another user (same URL as when clicking on red arrow). As a spectator, you should be able to see the game as if you were sitting beside of the players at a real table: all public information, no private information.
** Game is tested with in-game replay from last move feature (by clicking on notification log items)
** Game works in Chrome and Firefox browsers at least. Also very recommended to test in IE 11 and Edge.
** Game works on mobile device (if you don't have mobile device to test at least test in Chrome with smaller screen, they have a mode for that)
** Test your game in realtime mode. Usually people will run out of time if you use default times unless you add call giveExtraTime($active_player_id) before each turn
** Test your game in 3D mode (if it makes sense; 3D mode can also be disabled through the 'enable_3d' parameter for gameinfos.inc.php, but if it "mostly works", it can be nice to keep it activated even if 2D is more appropriate for the game, just because it's fun to look at)
** Check your game against the waiting screen, otherwise game start can fail. See [[Practical_debugging#Debugging_an_issue_with_the_waiting_screen]]
* Cleanup
** Remove all extra console.log from your js code
** Remove all unnecessary debug logging from your php code
** Copyright headers in all source files have your name
* User Interface
** Review BGA UI design Guidelines [[BGA_Studio_Guidelines]]
** Check all your English messages for proper use of punctuation, capitalization, usage of present tense in notification (not past) and gender neutrality. See [[Translations]] for English rules.
** If the elements in your game zone don't occupy all the available horizontal space, '''they should be centered'''.
** If your game elements become blurry or pixellated when using the browser zoom, you may want to consider [[Game_art:_img_directory#Use_background-size | higher resolution images with background-size]]
** Non-self explanatory graphic elements should have tooltips
** If graphic elements appear in notification log they should have titles (i.e. title attribute of div) so can be read in non rendered form (i.e. as text only)
** Strings in your source code are ready for translation. See [[Translations]]. You can generate dummy translations for checking that everything is ready for translation from your "Manage game" page.
** A prefix for example a trigram for your game that you prepend to all the css classes to avoid namespace conflicts, i.e. vla_selected vs selected
** If you are looking for advice on design and some 3rd party testing you can post a message on the developers forum, and ask other developers, there are a lot of people who will gladly do it.
* Finally move to Alpha status
** If possible (meaning if there is not already a project with that name) copy your project to a new project '''matching exactly the name of the game''' (no prefix or suffix). If not possible move on to the next steps, admin will have to retrieve the other project and overwrite it.
** Create a build for your game from the "manage game" page (using the '''Build a new release version''' section) and check the log to make sure that everything builds fine (after a successful build, you should see a new version in "Versions available for production").
** Send an e-mail to studio@boardgamearena.com asking to move the project forward for review. You cannot deploy yourself from the "manage game" page until a first deploy has been done by the admins. Please note that '''everything must be OK on the licensing''' side for a project to be moved to production.
** When admins publish (push to alpha) they will send an email to the developer with all relevant information about the next steps.

Pre-release checklist

2021-06-06T05:12:37Z

User Already Exists: typos

{{Studio_Framework_Navigation}}

If you think your game is ready to be reviewed by by BGA admins and/or Publisher please consult this checklist first

* Metadata and graphics
** [[Game_meta-information: gameinfos.inc.php]] has correct and up to date information about the game
** Game box graphics is 3D version of the game box (if available) and publisher icon is correct (see [[Game art: img directory]]). Space around the box has to be transparent, not white.
** You have added a game_banner.jpg and some game_displayX.jpg images to make the game page pretty (NB: on the studio, you have to create a build for these images to appear on the studio game page)
** There are no images in the img directory that are not needed anymore
** Multiple images (i.e. cards) are compressed in "Sprite" (see [[Game art: img directory]])
** Each image should not exceed 4M
** Total size should not exceed 10M, image compression should be used otherwise
** If you use extra fonts, they should be freeware (please include a .txt with the licence information)
* Server side
** When giving their turn to a player, you give them some extra time with the giveExtraTime() function
** Game progression is implemented (getGameProgression() in php)
** Zombie turn is implemented (zombieTurn() in php). Note: it can only be tested if you explicitly click on the quit button to create a zombie. If you are expelled it does not generated a Zombie.
** You have defined and implemented some meaningful statistics for your game (i.e. total points, point from source A, B, C...)
** Game has meaningful notification messages (but don't overkill it, more user logs will slow down the loading)
** You implemented tiebreaking (using aux score field) and updated tiebreaker description in meta-data
* Client side
** Please check that you use ajaxcall only on player actions and never programmatically. Otherwise, your code will very likely create race conditions resulting in deadlocks or other errors.
* Special testing
** Game is tested with spectator (non player observer): change the testuser in the URL to see the game as another user (same URL as when clicking on red arrow). As a spectator, you should be able to see the game as if you were sitting beside of the players at a real table: all public information, no private information.
** Game is tested with in-game replay from last move feature (by clicking on notification log items)
** Game works in Chrome and Firefox browsers at least. Also very recommended to test in IE 11 and Edge.
** Game works on mobile device (if you don't have mobile device to test at least test in Chrome with smaller screen, they have a mode for that)
** Test your game in realtime mode. Usually people will run out of time if you use default times unless you add call giveExtraTime($active_player_id) before each turn
** Test your game in 3D mode (if it makes sense; 3D mode can also be disabled through the 'enable_3d' parameter for gameinfos.inc.php, but if it "mostly works", it can be nice to keep it activated even if 2D is more appropriate for the game, just because it's fun to look at)
** Check your game against the waiting screen, otherwise game start can fail. See [[Practical_debugging#Debugging_an_issue_with_the_waiting_screen]]
* Cleanup
** Remove all extra console.log from your js code
** Remove all unnecessary debug logging from your php code
** Copyright headers in all source files have your name
* User Interface
** Review BGA UI design Guidelines [[BGA_Studio_Guidelines]]
** Check all your English messages for proper use of punctuation, capitalization, usage of present tense in notification (not past) and gender neutrality. See [[Translations]] for English rules.
** If the elements in your game zone don't occupy all the available horizontal space, '''they should be centered'''.
** If your game elements become blurry or pixellated when using the browser zoom, you may want to consider [[Game_art:_img_directory#Use_background-size | higher resolution images with background-size]]
** Non-self explanatory graphic elements should have tooltips
** If graphic elements appear in notification log they should have titles (i.e. title attribute of div) so can be read in non rendered form (i.e. as text only)
** Strings in your source code are ready for translation. See [[Translations]]. You can generate dummy translations for checking that everything is ready for translation from your "Manage game" page.
** A prefix for example a trigram for your game that you append to all the css classes to avoid namespace conflicts, i.e. vla_selected vs selected
** If you are looking for advice on design and some 3rd party testing you can post a message on the developers forum, and ask other developers, there are a lot of people who will gladly do it.
* Finally move to Alpha status
** If possible (meaning if there is not already a project with that name) copy your project to a new project '''matching exactly the name of the game''' (no prefix or suffix). If not possible move on to the next steps, admin will have to retrieve the other project and overwrite it.
** Create a build for your game from the "manage game" page (using the '''Build a new release version''' section) and check the log to make sure that everything builds fine (after a successful build, you should see a new version in "Versions available for production").
** Send an e-mail to studio@boardgamearena.com asking to move the project forward for review. You cannot deploy yourself from the "manage game" page until a first deploy has been done by the admins. Please note that '''everything must be OK on the licensing''' side for a project to be moved to production.
** When admins publish (push to alpha) they will send an email to the developer with all relevant information about the next steps.

Pre-release checklist

2021-06-06T05:12:07Z

User Already Exists: Fixed typos

{{Studio_Framework_Navigation}}

If you think your game is ready to be reviewed by by BGA admins and/or Publisher please consult this checklist first

* Metadata and graphics
** [[Game_meta-information: gameinfos.inc.php]] has correct and up to date information about the game
** Game box graphics is 3D version of the game box (if available) and publisher icon is correct (see [[Game art: img directory]]). Space around the box has to be transparent, not white.
** You have added a game_banner.jpg and some game_displayX.jpg images to make the game page pretty (NB: on the studio, you have to create a build for these images to appear on the studio game page)
** There is no images in img directory which are not needed anymore
** Multiple images (i.e. cards) are compressed in "Sprite" (see [[Game art: img directory]])
** Each image should not exceed 4M
** Total size should not exceed 10M, image compression should be used otherwise
** If you use extra fonts, they should be freeware (please include a .txt with the licence information)
* Server side
** When giving their turn to a player, you give them some extra time with the giveExtraTime() function
** Game progression is implemented (getGameProgression() in php)
** Zombie turn is implemented (zombieTurn() in php). Note: it can only be tested if you explicitly click on the quit button to create a zombie. If you are expelled it does not generated a Zombie.
** You have defined and implemented some meaningful statistics for your game (i.e. total points, point from source A, B, C...)
** Game has meaningful notification messages (but don't overkill it, more user logs will slow down the loading)
** You implemented tiebreaking (using aux score field) and updated tiebreaker description in meta-data
* Client side
** Please check that you use ajaxcall only on player actions and never programmatically. Otherwise, your code will very likely create race conditions resulting in deadlocks or other errors.
* Special testing
** Game is tested with spectator (non player observer): change the testuser in the URL to see the game as another user (same URL as when clicking on red arrow). As a spectator, you should be able to see the game as if you were sitting beside of the players at a real table: all public information, no private information.
** Game is tested with in-game replay from last move feature (by clicking on notification log items)
** Game works in Chrome and Firefox browsers at least. Also very recommended to test in IE 11 and Edge.
** Game works on mobile device (if you don't have mobile device to test at least test in Chrome with smaller screen, they have a mode for that)
** Test your game in realtime mode. Usually people will run out of time if you use default times unless you add call giveExtraTime($active_player_id) before each turn
** Test your game in 3D mode (if it makes sense; 3D mode can also be disabled through the 'enable_3d' parameter for gameinfos.inc.php, but if it "mostly works", it can be nice to keep it activated even if 2D is more appropriate for the game, just because it's fun to look at)
** Check your game against the waiting screen, otherwise game start can fail. See [[Practical_debugging#Debugging_an_issue_with_the_waiting_screen]]
* Cleanup
** Remove all extra console.log from your js code
** Remove all unnecessary debug logging from your php code
** Copyright headers in all source files have your name
* User Interface
** Review BGA UI design Guidelines [[BGA_Studio_Guidelines]]
** Check all your English messages for proper use of punctuation, capitalization, usage of present tense in notification (not past) and gender neutrality. See [[Translations]] for English rules.
** If the elements in your game zone don't occupy all the available horizontal space, '''they should be centered'''.
** If your game elements become blurry or pixellated when using the browser zoom, you may want to consider [[Game_art:_img_directory#Use_background-size | higher resolution images with background-size]]
** Non-self explanatory graphic elements should have tooltips
** If graphic elements appear in notification log they should have titles (i.e. title attribute of div) so can be read in non rendered form (i.e. as text only)
** Strings in your source code are ready for translation. See [[Translations]]. You can generate dummy translations for checking that everything is ready for translation from your "Manage game" page.
** A prefix for example a trigram for your game that you append to all the css classes to avoid namespace conflicts, i.e. vla_selected vs selected
** If you are looking for advice on design and some 3rd party testing you can post a message on the developers forum, and ask other developers, there are a lot of people who will gladly do it.
* Finally move to Alpha status
** If possible (meaning if there is not already a project with that name) copy your project to a new project '''matching exactly the name of the game''' (no prefix or suffix). If not possible move on to the next steps, admin will have to retrieve the other project and overwrite it.
** Create a build for your game from the "manage game" page (using the '''Build a new release version''' section) and check the log to make sure that everything builds fine (after a successful build, you should see a new version in "Versions available for production").
** Send an e-mail to studio@boardgamearena.com asking to move the project forward for review. You cannot deploy yourself from the "manage game" page until a first deploy has been done by the admins. Please note that '''everything must be OK on the licensing''' side for a project to be moved to production.
** When admins publish (push to alpha) they will send an email to the developer with all relevant information about the next steps.

Translation guidelines

2021-06-05T21:48:32Z

User Already Exists: /* When will the site be made available in a new language it is being translated into? */ typo

<div style="border:3px solid red; background-color: #FF6666; color: white; font-weight:normal; padding: 1em;">
This content is deprecated. Please refer to the up to date "Frequently Asked Questions" page at this address: https://boardgamearena.com/#!faq
</div>

The [http://en.boardgamearena.com/#!translationhq collaborative translation system] is meant to make it possible to translate Board Game Arena into any language, in order to enable more people to discover and play board games, even when not knowing English or French. For example, if you want to play 'Dragonheart' with your 10-year-old nephew and he doesn't speak English yet, no problem! Just help us translate Board Game Arena into your language!

== What can be translated? ==

Every string of text for the main site interface and for the games' interfaces are 'internationalized' and can be translated.
For now, forum posts and articles of the website (such as this one), cannot be translated. Maybe sometime later...

== Who should translate? ==

This is important: only translate text into a given language if you are a native speaker of the language.
When translating a game, the translator should know the game thoroughly and if possible have a box and rulebook of the game in the destination language to check for consistency. Translators should take into account the level of language and the formal/informal pronominal rules usual for the gaming audience of their country.

The source/reference language for translation is English, since the site and games development is made in English.

English is not necessarily the mother tongue of all developers, so the English strings are open for review and correction by native English speakers under the same conditions as the other languages, with a warning indicating that the change affects the source language and asking for confirmation.

== About context ==

Some strings can be translated differently depending upon the context. When this is the case, you should use the most obvious translation. Then when the site has been released in your language, native speakers will spot incorrect forms (if any) while playing and be able to correct them.

Also, you can ask us for context in the [http://forum.boardgamearena.com/viewforum.php?f=11 translation forum] (in English or in French), and we will try to look it up and provide the information.

== When will the site be made available in a new language it is being translated into? ==

As soon as a sufficient number of the strings have been translated into the new language in order for the site to make sense in that language, the Board Game Area team will make the site available in the language.

== I fixed some translations, but they don't appear to have changed on the site ==

Translation files are updated nightly, so you just have to wait till tomorrow for your changes to appear on the site.

== How long will it be possible to change the translations? ==

The first translations may not be perfect (as explained in the 'about context' section).
So they can be modified until they are 'validated'. Validation occurs when a translation has not been modified for 30 days straight. It is then considered stable and valid (golden icon) and cannot be changed anymore.

== Is there some reward for translating? ==

Yes! Every translator that gets 100 translations validated (golden icon) will get one free month of 'Board Game Arena Club' membership (and one more month for every batch of 100 new translations validated).

This is of course only a symbolic gesture of thanks for people participating in making BGA accessible to more and more people. The possibility to enjoy board games with people from many countries is the greatest reward of all!

== Translation tips ==

* Use the 'TAB' key to go from one text box to another. This is easier than clicking.

* Strings such as ${SOMETHING}, %SOMETHING, <SOMETHING> are markup strings for formatting or substituting text and must be left as is. Their position in the overall string can be changed as appropriate in a given language (for example for pronouns such as ${you}).

* When in doubt, leave a comment for the next translator.

* When you fix someone's translation, leave a comment if the reason for the change is not obvious.

* When the translation can depend on context which is not explicit, go with the most straightforward translation. If it is not correct, it will be spotted and fixed later by native speakers while playing.

Game interface logic: Game.js

2021-05-26T19:19:54Z

User Already Exists: /* Confirmation dialog */ grammar

{{Studio_Framework_Navigation}}

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 a change from the server and how it will show in the browser.

== File structure ==

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

Here is the basic structure:

* '''constructor''': here you can define global variables for your whole interface.
* '''setup''': this method is called when the page is refreshed, and sets up the game interface.
* '''onEnteringState''': this method is called when entering a new game state. You can use it to customize the view for each game state.
* '''onLeavingState''': this method is called when leaving a game state.
* '''onUpdateActionButtons''': called when entering a new state, in order to add action buttons to the status bar.
* ''(utility methods)'': this is where you can define your utility methods.
* ''(player's actions)'': this is where you can write your handlers for player actions on the interface (example: click on an item).
* '''setupNotifications''': this method associates notifications with notification handlers. For each game notification, you can trigger a javascript method to handle it and update the game interface.
* ''(notification handlers)'': this is where you define the notifications handlers associated with notifications in '''setupNotifications''', above.

More details:

;onEnteringState(stateName, args)
This method is called each time we are entering into a new game state.
You can use this method to perform some user interface changes at this moment.
To access state arguments passed via calling arg* method use args.args.
Typically you would do something only for active player, using this.isCurrentPlayerActive() check.

'''Warning''': for multipleactiveplayer states:
the active players are NOT actives yet so you must use onUpdateActionButtons to perform the client side operation which depends on a player active/unactive status.
If you are doing initialization of some structure which do not depend on active player, you can just replace
if (this.isCurrentPlayerActive()) {
into
if (!this.isSpectator) {
for the main switch in that method.

;onLeavingState(stateName)
This method is called each time we are leaving a game state.
You can use this method to perform some user interface changes at this moment.

;onUpdateActionButtons(stateName, args)
In this method you can manage "action buttons" that are displayed in the action status bar.
To access state arguments passed via calling arg* method use args parameter. Note: args can be null! For game states and when you don't supply state args function it is null.
This method is called when active or multiactive player changes. In classic "activePlayer" state this method is called before the onEnteringState state.
In multipleactiveplayer state it is a mess. The sequencing of call would depends on either you get into that from transition from reloading the whole game (i.e. F5).

See more details in [[Your_game_state_machine:_states.inc.php#Diffrence_between_Single_active_and_Multi_active_states]]

== 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: This is a variable, not a function.
: Note: If you want to hide an element from spectators, you should use [[Game_interface_stylesheet:_yourgamename.css#spectatorMode|CSS 'spectatorMode' class]].

; this.gamedatas
: Contains the initial set of data to init the game, created at game start or by 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 this is unnecessary).

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

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

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

; this.bRealtime
: Return true if the game is in realtime. Note that having a distinct behavior in realtime and turn-based should be exceptional.

; typeof g_replayFrom != 'undefined'
: Returns true if the game is in replay mode <i>during the game</i> (the game is ongoing but the user clicked "reply from this move" in the log)

; g_archive_mode
: Returns true if the game is in archive mode <i>after the game</i> (the game has ended)

; this.instantaneousMode
: Returns true during replay/archive mode if animations should be skipped. Only needed if you are doing custom animations. (The BGA-provided animation functions like <i>this.slideToObject()</i> automatically handle instantaneous mode.)
: Technically, when you click "replay from move #20", the system replays the game from the very beginning with moves 0 - 19 happening in instantaneous mode and moves 20+ happening in normal mode.

---

You may consider making a function like this, to detect if the game is in a read-only state:

// Returns true for spectators, instant replay (during game), archive mode (after game end)
isReadOnly: function () {
return this.isSpectator || typeof g_replayFrom != 'undefined' || g_archive_mode;
}

== Dojo framework ==

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

The Dojo framework allows us to do complex things more easily. The BGA framework uses Dojo extensively.

To implement a game, you only need to use a few parts of the Dojo framework. All the Dojo methods you need are described on this page.

== Javascript minimization (before July 2020) ==

For performance reasons, when deploying a game the js code is minimized using ShrinkSafe (based on ECMASCRIPT version 3). Some advanced syntax may not be compatible with this process. In particular:
* You should not use reserved keywords from the javascript language as variables.
* You should not declare default argument values in function declarations. The following syntax is invalid for ShrinkSafe: '''function myFunc(requiredArg, optionalArg = 'defaultValue') {}'''
* You should not use '''let''' or '''const''' to declare variables.

'''Tip:''' a developer encountering some problems with this has successfully used [http://plugins.netbeans.org/plugin/58580/jshint JSHint] on NetBeans to evaluate code to make it compatible for ECMAScript 3. With the plugin installed, set the below options in '''.jshintrc''' file, and then open '''Action Items''' window (in NetBeans):<pre>{ "maxerr": 999, "esversion": 3 }</pre>

'''Tip:''' some online tools also allow to convert between different versions of javascript, such as https://www.typescriptlang.org/play or https://babeljs.io/ or https://extendsclass.com/javascript-fiddle.html

== Javascript minimization (after July 2020) ==

For performance reasons, when deploying a game the javascript code is minimized using '''terser''' (https://github.com/terser/terser). This minifier works with modern javascript syntax. From your project "Manage game" page, you can now test a minified version of your javascript on the studio (and revert to the original).

NB: it has been reported that there is an issue with this minifier and percentage values for opacity.

== Accessing and manipulating the DOM ==

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

The $() function is used to get an 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 the BGA Framework. You can use '''getElementById''' but a longer to type and less handy as it does not do some checks.
Note²: It is safe to use if you don't know if variable is string (id of element) or element itself, i.e.
<pre>
foo: function(card) {
card = $(card); // now its node, no need to write if (typeof card === 'string') ...
// but its good idea to check for null here
...
}
</pre>

'''dojo.style'''

With dojo.style you can modify the CSS property of any HTML element in 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 sprites to transform an element to another)
dojo.style( 'my_element', 'backgroundPosition', '-20px -50px' );
</pre>

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

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

'''Vanila JS style'''
$('my_element').style.display='none'; // set
var display = $('my_element').style.display; // get
$('my_element').style.removeProperty('display'); // remove

'''dojo.addClass''', '''dojo.removeClass''', '''dojo.hasClass''', '''dojo.toggleClass'''

In many situations, many small CSS property updates can be replaced by a CSS class change (i.e., you add a CSS class to your element instead of applying all modifications 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 without error.
* You can test whether you applied the CSS to an element with the '''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 changes in one line of code.

// ... and when we need to check if a square is a possible move on the 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.attr'''

With dojo.attr you can access or change the value of an attribute or property of any HTML element in your interface.

Exemple:
<pre>
// Get the title of a node
var title = dojo.attr( id, 'title' );
// Change the height of a node
dojo.attr( 'img_growing_tree', 'height', 100 );
</pre>

'''Vanila JS attr'''

$(token).id=new_id; // set attr for "id"
var id = $(token).id; // get

'''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 (i.e., elements of class "token") on the board (i.e., the 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>

'''Vanila JS query'''

var cards=document.querySelectorAll(".hand .card");// all cards in all hands
var cards=$('hand').querySelectorAll(".card");// all cards in specific hand
var card=document.querySelector(".hand .card");// first card or null if none (super handy)

'''dojo.place'''

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

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

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

</pre>

The third parameter of dojo.place can take various interesting values:

"replace" : (see description above).

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

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

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

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

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

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

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

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]]".

But you can also relocate elements like that. Note: it won't animate if you do that.

'''dojo.empty'''

Remove all children of the node element
dojo.empty('my_hand');

'''dojo.destroy'''

Remove the element

dojo.query(".green", mynode).forEach(dojo.destroy); // this remove all subnode of class green from mynode

'''dojo.create'''

Create element

dojo.create("div", { class: "yellow_arrow" }, parent); // this creates div with class yellow_array and places it in "parent"

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

Note 2: the slideTo methods are not compatible with CSS transform (scale, zoom, rotate...). If possible, avoid using CSS transform on nodes that are being slided. Eventually, the only possible solution to make these 2 compatible is to disable all CSS transform properties, use slideToObjectPos/placeOnObjectPos, and then apply them again.

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

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

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

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

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

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

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

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

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

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

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

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

Example:
<pre>
this.slideTemporaryObject( '<div class="token_icon"></div>', 'tokens', 'my_origin_div', 'my_target_div' ).play();
</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, but it starts the animation.

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

'''this.fadeOutAndDestroy( node, duration, delay )'''

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

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>

Note: This wiki was probably written 10 years ago - now all modern broser support 'transform' so just ignore this and use transform.

'''Animation Callbacks'''

If you wish to run some code only after an animation has completed you can do this by linking a callback method.

<pre>
var animation_id = this.slideToObject( mobile_obj, target_obj, duration, delay );
dojo.connect(animation_id, 'onEnd', dojo.hitch(this, 'callback_function', parameters));
animation_id.play();

…

callback_function: function(params) {
// this will be called after the animation ends
},
</pre>

If you wish to call a second animation after the first (rather than general code) then you can use a dojo animation chain (see tutorial referenced above).

=== Moving elements ===

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

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

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

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

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

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

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

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

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

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

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

Why using this method?

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

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

== Players input ==

'''dojo.connect'''

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

Example: associate a click on an element ("my_element") with one of our methods ("onClickOnMyElement"):
<pre>
dojo.connect( $('my_element'), 'onclick', this, 'onClickOnMyElement' );
</pre>
Same idea but base on query (i.e. all element of 'pet' class)
dojo.query(".pet").connect('onclick', this, 'onPet');

Note: the methods described here are the only correct ways to associate a player input event to your code, and you should not use anything else.

'''this.connect'''
function(element, event, handler)

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

this.connect( $('my_element'), 'onclick', 'onClickOnMyElement' );

Or you can use an in-place handler

this.connect( $('my_element'), 'onclick', (e) => { console.log('boo'); } );

Note that this function stores the connection handler. That is the only real difference between '''this.connect''' and '''dojo.connect'''. If you plan to destroy the element you connected, you '''must''' call this.disconnect() to prevent memory leaks.

'''this.connectClass'''
function( cssClassName, event, handler )

Same as connect(), but for all the nodes set with the specified cssClassName.
<pre>
this.connectClass('pet', 'onclick', 'onPet');
</pre>
'''this.disconnect'''
function( element, event )

Disconnect event handler (previously registered with this.connect or this.connectClass).

this.disconnect( $('my_element'), 'onclick');

Note: dynamic connect/disconnect is for advanced cases ONLY, you should always connect elements statically if possible, i.e. in setup() method.

'''this.disconnectAll'''

Disconnect all previously registed event handlers (registered via this.connect or this.connectClass)

'''this.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 (i.e: the action is listed as a "possibleaction" in current game state).

return false and display an error message if not authorized (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.checkPossibleActions'''
function( action, nomessage )

* this is independent of the player being active, so can be used instead of this.checkAction(). This is particularly useful for multiplayer states when the player is not active in a 'player may like to change their mind' scenario.

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)

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

This method must be used to send a player input to the game server. '''It should not be triggered programmatically''', especially not in loops, in callbacks, in notifications, or in onEnteringState/onUpdateActionButtons/onLeavingState, in order not to create race conditions.

* 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 parameters in order the interface can be locked during the server call.
** Note: Restricted parameter names (please don't use them):
*** "action"
*** "module"
*** "class"
* obj_callback: must be set to "this".
* callback: a function to trigger when the server returns and everything went fine (not used, as all data handling is done via notifications).
* callback_error: (optional and rarely used) a function to trigger when the server returns an error. if no error this function is called with parameter value false.

Usage:
<pre>
this.ajaxcall( '/mygame/mygame/myaction.html', { lock: true,
arg1: myarg1,
arg2: myarg2,
...
}, this, function( result ) {
// Do some stuff after a successful call
// NB : usually not needed as changes must be handled by notifications
// You should NOT modify the interface in a callback or it will most likely break the framework replays (or make it inaccurate)
// You should NOT make another ajaxcall in a callback in order not to create race conditions
} );
</pre>

Note: to reduce the boilerplate code you can define your own wrapper, which will do checking, locking and allow to skip parameters, for example
<pre>
ajaxcallwrapper: function(action, args, handler) {
if (!args) {
args = [];
}
args.lock = true;

if (this.checkAction(action)) {
this.ajaxcall("/" + this.game_name + "/" + this.game_name + "/" + action + ".html", args,//
this, (result) => { }, handler);
}
},
</pre>
This can be called like this which is a lot more compact
<pre>
this.ajaxcallwrapper('playDraw');
this.ajaxcallwrapper('playMove', {card: id})
</pre>

'''this.isInterfaceLocked()'''

When using "lock: true" in ajax call you can use this function to check if interface is in lock state (it will be locked during server call and notification processing).
This check can be used to block some other interactions which do not result in ajaxcall or if you want to suppress errors.

'''this.addActionButton( id, label, method, (opt)destination, (opt)blinking, (opt)color )'''

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

Arguments:
* id: an element 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.
* destination (optional): deprecated, do not use this. Use '''null''' as value if you need to specify other arguments.
* blinking (optional): if set to '''true''', the button is going blink to catch player's attention. Please don't abuse of blinking button.
* color: could be '''blue''' (default), '''red''' or '''gray'''.

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

<pre>
onUpdateActionButtons: function( stateName, args ) {

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.

Example using blinking red button:
<pre>
this.addActionButton( 'commit_button', _('Confirm'), 'onConfirm', null, true, 'red');
</pre>

Note: at least in studio example above will make button huge, because it sets it display of blinking things to '''block''',
if you don't like it you have to change css display value
of the button to inline-block (the id of the button is the first argument, i.e 'commit_button' in example above)

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

-----

It is also possible to control the delay timing dynamically (e.g., using notification args). As an example, maybe your notification 'cardPlayed' should pause for a different amount of time depending on the number or type of cards played.

For this case, use '''setSynchronous''' without specifying the duration and use '''setSynchronousDuration''' within the notification callback.

* NOTE: If you forget to invoke '''setSynchronousDuration''', the game will remain paused forever!

<pre>
setupNotifications: function () {
dojo.subscribe( 'cardPlayed', this, 'notif_cardPlayed' );
this.notifqueue.setSynchronous( 'cardPlayed' ); // wait time is dynamic
...
},

notif_cardPlayed: function (notif) {
// MUST call setSynchronousDuration

// Example 1: From notification args (PHP)
this.notifqueue.setSynchronousDuration(notif.args.duration);
...

// Or, example 2: Match the duration to a Dojo animation
var anim = dojo.fx.combine([
...
]);
anim.play();
this.notifqueue.setSynchronousDuration(anim.duration);
},
</pre>

=== Ignoring notifications ===
Sometimes you need to ignore some notification on client side. You don't want them to be shown in game log and you don't want them to be handled.

The most common use case is when a player gets private information. They will receive a specific notification (such as "You received Ace of Heart"), while other players would receive more generic notification ("Player received a card").

In X.game.php
<pre>
$this->notifyAllPlayers("dealCard", clienttranslate('${player_name} received a card'), [
'player_id' => $playerId,
'player_name' => $this->getActivePlayerName()
]);

$this->notifyPlayer($playerId, "dealCardPrivate", clienttranslate('You received ${cardName}'), [
"type" => $card["type"],
"cardName" => $this->getCardName($card["type"])
]);
</pre>

The problem with this approach is that the active player will receive two notifications:
* Player1 received a card
* You received Ace of Hearts

Hence, notification ignoring. Similar to setting a synchronous notification above, you can set up a check whether a notification should be ignored:
<pre>
this.notifqueue.setIgnoreNotificationCheck( 'dealCard', (notif) => (notif.args.player_id == this.player_id) );
</pre>

'''setIgnoreNotificationCheck(notificationId, predicate)'''
This method will set a check whether any of notifications of specific type should be ignored.

The parameters are:
* notificationId: before dispatching any notification of this type, the framework will call predicate to check whether notification should be ignored
* predicate (notif => boolean): a function that will receive notif object and will return true if this specific notification should be ignored

NOTE: You can think that it could be possible to send generic notification to all other players with notifyAllPlayers and it will seem to work. The problem is that table spectators would miss this notification and their user interface (and game log) wouldn't be updated.

IMPORTANT: Remember that this notification is ignored on the client side, but was still received by the client. Therefore it shouldn't contain any private information as cheaters can get it. In other words this is not a way to hide information.

IMPORTANT: When a game is reloaded with F5 or when opening a turn based game, old notifications are replayed as history notification. They are used just to update the game log and are stripped of all arguments except player_id, i18n and any argument present in message. If you use and other argument in your predicate you should preserve it as explained [[Main_game_logic:_yourgamename.game.php#Notify_players|here]].

=== Pre-defined notification types ===

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

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

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

'''simplePause''' - This notification will just delay other notifications, maybe useful if you know you need some extra time for animation or something. Requires a time parameter.

<pre>
self::notifyAllPlayers( 'simplePause', '', [ 'time' => 500] ); // time is in milliseconds
</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 should 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 browsers (see [[BGA_Studio_Guidelines|Guidelines]]).

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

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

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

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

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

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

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

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

IMPORTANT: all concerned nodes must have IDs to get tooltips

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

Remove a tooltip from the DOM node.

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

=== Warning messages ===

Sometimes, there is something important that is happening in 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 fulfills one of the end of the game conditions, 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 the current player.

* "msg" is the string to display. It should be translated.
* "type" can be set to "info", "error", or "only_to_log". 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. If set to "only_to_log", the message will be added to the game log but will not popup at the top of the screen.

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

'''confirmationDialog( message, yesHandler, noHandler )'''

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 guideline of BGA is to AVOID the use of confirmation dialogs. Confirmation dialogs slow down the game and bother players. The players know that they have to pay attention to each move when they are playing online.

The situations 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 does 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 bake the pie?'), dojo.hitch( this, function() {
this.bakeThePie();
} ) );
return; // nothing should be called or done after calling this, all action must be done in the handler
</pre>

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

=== Dialogs ===

As a general rule, you shouldn't use dialogs windows.

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

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

// Create the new dialog over the play zone. You should store the handler in a member variable to access it later
this.myDlg = new ebg.popindialog();
this.myDlg.create( 'myDialogUniqueId' );
this.myDlg.setTitle( _("my dialog title to translate") );
this.myDlg.setMaxWidth( 500 ); // Optional

// 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.setContent( html ); // Must be set before calling show() so that the size of the content is defined before positioning the dialog
this.myDlg.show();

// Now that the dialog has been displayed, you can connect your method to some dialog elements
// Example, if you have an "OK" button in the HTML of your dialog:
dojo.connect( $('my_ok_button'), 'onclick', this, function(evt){
evt.preventDefault();
this.myDlg.destroy();
} );

If necessary, you can remove the default top right corner 'close' icon, or replace the function called when it is clicked:
// Removes the default close icon
this.myDlg.hideCloseIcon();

// Replace the function call when it's clicked
this.myDlg.replaceCloseCallback( function() { ... } );

=== 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" => clienttranslate("a string with an ${argument}"), "args" => array( 'argument' => 'argument_value' ) ) ),
array( "four", "five", "six" ),
array( "seven", "height", "nine" )
);
</pre>

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

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

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

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

=== Scoring animated display ===

Sometimes (Terra Mystica final scoring for example), you may want to display a score value over an element to make the scoring easier to follow for the players.
You can do it with:

<pre>
this.displayScoring( anchor_id, color, score, duration, offset_x, offset_y );
</pre>

'''anchor_id''': ID of the element to place the animated score onto (without the '#')

'''color''': hexadecimal RGB representation of the color (should be the color of the scoring player), but without a leading '#'. For instance, 'ff0000' for red.

'''score''': numeric score to display, prefixed by a '+'

'''duration''': animation duration in milliseconds

'''offset_x''' and '''offset_y''': if both offset_x and offset_y are defined and not null, apply the following offset (in pixels) to the scoring animation. Note that the score is centered in the anchor, so the offsets might have to be negative if you calculate the position.

Note: if you want to display successively each score, you can use ''this.notifqueue.setSynchronous()'' function.

=== Speech bubble ===

For better interactivity in some games (Love Letter for example), you may use comic book style speech bubbles to express the players voices.
This is done with:

<pre>
this.showBubble(anchor_id, text, delay, duration, custom_class)
</pre>

text - what to put in bubble, can be html actually not just text

delay - in milliseconds is optional (default 0)

duration - in milliseconds is optional (default 3000)

custom_class - extra class to add to bubble is optional, if you need to override the default bubble style

'''Warning''': if your bubble could overlap other active elements of the interface (buttons in particular), as it stays in place even after disappearing, you should use a custom class to give it the style "pointer-events: none;" in order to intercept click events.

Note: If you want this visually, but want to take complete control over this bubble and its animation (for example to make it permanent) you can just use div with 'discussion_bubble' class on it, and content of div is what will be shown.

== Update players score ==

The column player_score from the player table is automatically loaded into this.scoreCtrl and therefore into the stars location on the player board. This occurs sometime after the <gamename>.js setup() function. However this score must be updated as the game progresses through player notifications (notifs).

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>

Set a player score to a specific value with animation :

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

Typical usage would be (that will process 'score' notification):
<pre>
setupNotifications : function() {
...
dojo.subscribe('score', this, "notif_score");
},
notif_score: function(notif) {
this.scoreCtrl[notif.args.player_id].setValue(notif.args.player_score);
},
</pre>

== Players panels ==

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Enable a player panel that has been disabled before.

'''this.enableAllPlayerPanels()'''

Enable all player panels that has been disabled before.

== Image loading ==

See also [[Game_art:_img_directory]].

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

'''dontPreloadImage( image_file_name )'''

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

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

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

Another example of use: in "Gosu" game with Kamakor extension, you play with 5 sets of cards among 10 available. Cards images are organized by sets, and we only preload the images corresponding to the 5 current sets with '''ensureSpecificGameImageLoading( image_file_names_array )'''.
<pre>
// By default, do not preload anything
this.dontPreloadImage( 'cards.png' );
this.dontPreloadImage( 'clan1.png' );
this.dontPreloadImage( 'clan2.png' );
this.dontPreloadImage( 'clan3.png' );
this.dontPreloadImage( 'clan4.png' );
this.dontPreloadImage( 'clan5.png' );
this.dontPreloadImage( 'clan6.png' );
this.dontPreloadImage( 'clan7.png' );
this.dontPreloadImage( 'clan8.png' );
this.dontPreloadImage( 'clan9.png' );
this.dontPreloadImage( 'clan10.png' );
var to_preload = [];
for( i in this.gamedatas.clans )
{
var clan_id = this.gamedatas.clans[i];
to_preload.push( 'clan'+clan_id+'.png' );
}
if( to_preload.length == 5 )
{
this.ensureSpecificGameImageLoading( to_preload );
}
</pre>

'''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 ensure that the "this" object will be set when the callback is called.

NOTE: In modern JS there are lambdas that eliminate need for that, the example above will look like this
<pre>
this.confirmationDialog( _('Are you sure you want to make this?'), () => {
this.ajaxcall( '/mygame/mygame/makeThis.html', { lock:true }, this, (result) => {} );
} );
</pre>

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

;'''onScreenWidthChange()'''
:This function can be overridden in your game to manage some resizing on the client side when the browser window is resized. This function is also triggered at load time, so it can be used to adapt to the :viewport size at the start of the game too.

;'''updatePageTitle()'''
:This function allows to update the current page title and turn description according to the game state. If the current game state description this.gamedatas.gamestate.descriptionmyturn is modified before :calling the function, it allows to update the turn description without changing state.

Example from Terra Mystica:
<pre>
onClickFavorTile: function( evt ) {
...
if ( ... ) {
this.gamedatas.gamestate.descriptionmyturn = _('Special action: ') + _('Advance 1 space on a Cult track');
this.updatePageTitle();
this.removeActionButtons();
this.addActionButton( ... );
...
return;
}
...

}
</pre>

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

== BGA Buttons ==

You can create a custom button, but the BGA framework provides a standard button that requires only .css classes: '''bgabutton''' and '''bgabutton_${color}'''.

'''Examples:'''

<pre>
<a href="#" id="my_button_id" class="bgabutton bgabutton_blue"><span>My blue button</span></a>
</pre>
<pre>
<a href="#" id="my_button_id" class="bgabutton bgabutton_gray"><span>My gray button</span></a>
</pre>
<pre>
<a href="#" id="my_button_id" class="bgabutton bgabutton_red"><span>My red button</span></a>
</pre>
<pre>
<a href="#" id="my_button_id" class="bgabutton bgabutton_red bgabutton_big"><span>My big red button</span></a>
</pre>

'''Note''': To see it in action, check out ''Coloretto''.

'''Disabling:'''
You can disable the '''bgabutton''' by adding the css class '''disabled''' in you js. The disabled button is still visible but is grey and not clickable.
For example in the '''onUpdateActionButtons''' :
<pre>this.addActionButton( 'play_button_id', _('Play 1 to 3 cards'), 'playFunctionButton', null, false, 'blue' ); //Create a blue button
if (Condition == true)
{
dojo.addClass( 'play_button_id', 'disabled');//disable the button
}</pre>

== Sounds ==

Add a custom sound and make it load with your interface:

Add this in your template (.tpl) file:
<pre>
<audio id="audiosrc_<gamename>_<yoursoundname>" src="{GAMETHEMEURL}img/<gamename>_<yoursoundname>.mp3" preload="none" autobuffer></audio>
<audio id="audiosrc_o_<gamename>_<yoursoundname>" src="{GAMETHEMEURL}img/<gamename>_<yoursoundname>.ogg" preload="none" autobuffer></audio>
</pre>

Note: this is a requirement to provide both a mp3 and a ogg file.

Play the sound (from your .js file):

<pre>
playSound('<gamename>_<yoursoundname>');
</pre>

Disable the standard "move" sound for this move (to replace it with your custom sound):

Add this to your notification handler:

<pre>
this.disableNextMoveSound();
</pre>

Note: it only disable the sound for the next move.

Game interface logic: Game.js

2021-05-26T19:18:00Z

User Already Exists: /* Warning messages */ grammar

{{Studio_Framework_Navigation}}

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 a change from the server and how it will show in the browser.

== File structure ==

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

Here is the basic structure:

* '''constructor''': here you can define global variables for your whole interface.
* '''setup''': this method is called when the page is refreshed, and sets up the game interface.
* '''onEnteringState''': this method is called when entering a new game state. You can use it to customize the view for each game state.
* '''onLeavingState''': this method is called when leaving a game state.
* '''onUpdateActionButtons''': called when entering a new state, in order to add action buttons to the status bar.
* ''(utility methods)'': this is where you can define your utility methods.
* ''(player's actions)'': this is where you can write your handlers for player actions on the interface (example: click on an item).
* '''setupNotifications''': this method associates notifications with notification handlers. For each game notification, you can trigger a javascript method to handle it and update the game interface.
* ''(notification handlers)'': this is where you define the notifications handlers associated with notifications in '''setupNotifications''', above.

More details:

;onEnteringState(stateName, args)
This method is called each time we are entering into a new game state.
You can use this method to perform some user interface changes at this moment.
To access state arguments passed via calling arg* method use args.args.
Typically you would do something only for active player, using this.isCurrentPlayerActive() check.

'''Warning''': for multipleactiveplayer states:
the active players are NOT actives yet so you must use onUpdateActionButtons to perform the client side operation which depends on a player active/unactive status.
If you are doing initialization of some structure which do not depend on active player, you can just replace
if (this.isCurrentPlayerActive()) {
into
if (!this.isSpectator) {
for the main switch in that method.

;onLeavingState(stateName)
This method is called each time we are leaving a game state.
You can use this method to perform some user interface changes at this moment.

;onUpdateActionButtons(stateName, args)
In this method you can manage "action buttons" that are displayed in the action status bar.
To access state arguments passed via calling arg* method use args parameter. Note: args can be null! For game states and when you don't supply state args function it is null.
This method is called when active or multiactive player changes. In classic "activePlayer" state this method is called before the onEnteringState state.
In multipleactiveplayer state it is a mess. The sequencing of call would depends on either you get into that from transition from reloading the whole game (i.e. F5).

See more details in [[Your_game_state_machine:_states.inc.php#Diffrence_between_Single_active_and_Multi_active_states]]

== 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: This is a variable, not a function.
: Note: If you want to hide an element from spectators, you should use [[Game_interface_stylesheet:_yourgamename.css#spectatorMode|CSS 'spectatorMode' class]].

; this.gamedatas
: Contains the initial set of data to init the game, created at game start or by 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 this is unnecessary).

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

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

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

; this.bRealtime
: Return true if the game is in realtime. Note that having a distinct behavior in realtime and turn-based should be exceptional.

; typeof g_replayFrom != 'undefined'
: Returns true if the game is in replay mode <i>during the game</i> (the game is ongoing but the user clicked "reply from this move" in the log)

; g_archive_mode
: Returns true if the game is in archive mode <i>after the game</i> (the game has ended)

; this.instantaneousMode
: Returns true during replay/archive mode if animations should be skipped. Only needed if you are doing custom animations. (The BGA-provided animation functions like <i>this.slideToObject()</i> automatically handle instantaneous mode.)
: Technically, when you click "replay from move #20", the system replays the game from the very beginning with moves 0 - 19 happening in instantaneous mode and moves 20+ happening in normal mode.

---

You may consider making a function like this, to detect if the game is in a read-only state:

// Returns true for spectators, instant replay (during game), archive mode (after game end)
isReadOnly: function () {
return this.isSpectator || typeof g_replayFrom != 'undefined' || g_archive_mode;
}

== Dojo framework ==

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

The Dojo framework allows us to do complex things more easily. The BGA framework uses Dojo extensively.

To implement a game, you only need to use a few parts of the Dojo framework. All the Dojo methods you need are described on this page.

== Javascript minimization (before July 2020) ==

For performance reasons, when deploying a game the js code is minimized using ShrinkSafe (based on ECMASCRIPT version 3). Some advanced syntax may not be compatible with this process. In particular:
* You should not use reserved keywords from the javascript language as variables.
* You should not declare default argument values in function declarations. The following syntax is invalid for ShrinkSafe: '''function myFunc(requiredArg, optionalArg = 'defaultValue') {}'''
* You should not use '''let''' or '''const''' to declare variables.

'''Tip:''' a developer encountering some problems with this has successfully used [http://plugins.netbeans.org/plugin/58580/jshint JSHint] on NetBeans to evaluate code to make it compatible for ECMAScript 3. With the plugin installed, set the below options in '''.jshintrc''' file, and then open '''Action Items''' window (in NetBeans):<pre>{ "maxerr": 999, "esversion": 3 }</pre>

'''Tip:''' some online tools also allow to convert between different versions of javascript, such as https://www.typescriptlang.org/play or https://babeljs.io/ or https://extendsclass.com/javascript-fiddle.html

== Javascript minimization (after July 2020) ==

For performance reasons, when deploying a game the javascript code is minimized using '''terser''' (https://github.com/terser/terser). This minifier works with modern javascript syntax. From your project "Manage game" page, you can now test a minified version of your javascript on the studio (and revert to the original).

NB: it has been reported that there is an issue with this minifier and percentage values for opacity.

== Accessing and manipulating the DOM ==

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

The $() function is used to get an 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 the BGA Framework. You can use '''getElementById''' but a longer to type and less handy as it does not do some checks.
Note²: It is safe to use if you don't know if variable is string (id of element) or element itself, i.e.
<pre>
foo: function(card) {
card = $(card); // now its node, no need to write if (typeof card === 'string') ...
// but its good idea to check for null here
...
}
</pre>

'''dojo.style'''

With dojo.style you can modify the CSS property of any HTML element in 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 sprites to transform an element to another)
dojo.style( 'my_element', 'backgroundPosition', '-20px -50px' );
</pre>

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

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

'''Vanila JS style'''
$('my_element').style.display='none'; // set
var display = $('my_element').style.display; // get
$('my_element').style.removeProperty('display'); // remove

'''dojo.addClass''', '''dojo.removeClass''', '''dojo.hasClass''', '''dojo.toggleClass'''

In many situations, many small CSS property updates can be replaced by a CSS class change (i.e., you add a CSS class to your element instead of applying all modifications 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 without error.
* You can test whether you applied the CSS to an element with the '''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 changes in one line of code.

// ... and when we need to check if a square is a possible move on the 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.attr'''

With dojo.attr you can access or change the value of an attribute or property of any HTML element in your interface.

Exemple:
<pre>
// Get the title of a node
var title = dojo.attr( id, 'title' );
// Change the height of a node
dojo.attr( 'img_growing_tree', 'height', 100 );
</pre>

'''Vanila JS attr'''

$(token).id=new_id; // set attr for "id"
var id = $(token).id; // get

'''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 (i.e., elements of class "token") on the board (i.e., the 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>

'''Vanila JS query'''

var cards=document.querySelectorAll(".hand .card");// all cards in all hands
var cards=$('hand').querySelectorAll(".card");// all cards in specific hand
var card=document.querySelector(".hand .card");// first card or null if none (super handy)

'''dojo.place'''

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

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

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

</pre>

The third parameter of dojo.place can take various interesting values:

"replace" : (see description above).

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

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

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

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

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

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

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

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]]".

But you can also relocate elements like that. Note: it won't animate if you do that.

'''dojo.empty'''

Remove all children of the node element
dojo.empty('my_hand');

'''dojo.destroy'''

Remove the element

dojo.query(".green", mynode).forEach(dojo.destroy); // this remove all subnode of class green from mynode

'''dojo.create'''

Create element

dojo.create("div", { class: "yellow_arrow" }, parent); // this creates div with class yellow_array and places it in "parent"

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

Note 2: the slideTo methods are not compatible with CSS transform (scale, zoom, rotate...). If possible, avoid using CSS transform on nodes that are being slided. Eventually, the only possible solution to make these 2 compatible is to disable all CSS transform properties, use slideToObjectPos/placeOnObjectPos, and then apply them again.

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

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

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

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

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

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

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

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

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

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

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

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

Example:
<pre>
this.slideTemporaryObject( '<div class="token_icon"></div>', 'tokens', 'my_origin_div', 'my_target_div' ).play();
</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, but it starts the animation.

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

'''this.fadeOutAndDestroy( node, duration, delay )'''

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

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>

Note: This wiki was probably written 10 years ago - now all modern broser support 'transform' so just ignore this and use transform.

'''Animation Callbacks'''

If you wish to run some code only after an animation has completed you can do this by linking a callback method.

<pre>
var animation_id = this.slideToObject( mobile_obj, target_obj, duration, delay );
dojo.connect(animation_id, 'onEnd', dojo.hitch(this, 'callback_function', parameters));
animation_id.play();

…

callback_function: function(params) {
// this will be called after the animation ends
},
</pre>

If you wish to call a second animation after the first (rather than general code) then you can use a dojo animation chain (see tutorial referenced above).

=== Moving elements ===

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

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

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

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

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

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

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

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

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

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

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

Why using this method?

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

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

== Players input ==

'''dojo.connect'''

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

Example: associate a click on an element ("my_element") with one of our methods ("onClickOnMyElement"):
<pre>
dojo.connect( $('my_element'), 'onclick', this, 'onClickOnMyElement' );
</pre>
Same idea but base on query (i.e. all element of 'pet' class)
dojo.query(".pet").connect('onclick', this, 'onPet');

Note: the methods described here are the only correct ways to associate a player input event to your code, and you should not use anything else.

'''this.connect'''
function(element, event, handler)

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

this.connect( $('my_element'), 'onclick', 'onClickOnMyElement' );

Or you can use an in-place handler

this.connect( $('my_element'), 'onclick', (e) => { console.log('boo'); } );

Note that this function stores the connection handler. That is the only real difference between '''this.connect''' and '''dojo.connect'''. If you plan to destroy the element you connected, you '''must''' call this.disconnect() to prevent memory leaks.

'''this.connectClass'''
function( cssClassName, event, handler )

Same as connect(), but for all the nodes set with the specified cssClassName.
<pre>
this.connectClass('pet', 'onclick', 'onPet');
</pre>
'''this.disconnect'''
function( element, event )

Disconnect event handler (previously registered with this.connect or this.connectClass).

this.disconnect( $('my_element'), 'onclick');

Note: dynamic connect/disconnect is for advanced cases ONLY, you should always connect elements statically if possible, i.e. in setup() method.

'''this.disconnectAll'''

Disconnect all previously registed event handlers (registered via this.connect or this.connectClass)

'''this.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 (i.e: the action is listed as a "possibleaction" in current game state).

return false and display an error message if not authorized (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.checkPossibleActions'''
function( action, nomessage )

* this is independent of the player being active, so can be used instead of this.checkAction(). This is particularly useful for multiplayer states when the player is not active in a 'player may like to change their mind' scenario.

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)

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

This method must be used to send a player input to the game server. '''It should not be triggered programmatically''', especially not in loops, in callbacks, in notifications, or in onEnteringState/onUpdateActionButtons/onLeavingState, in order not to create race conditions.

* 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 parameters in order the interface can be locked during the server call.
** Note: Restricted parameter names (please don't use them):
*** "action"
*** "module"
*** "class"
* obj_callback: must be set to "this".
* callback: a function to trigger when the server returns and everything went fine (not used, as all data handling is done via notifications).
* callback_error: (optional and rarely used) a function to trigger when the server returns an error. if no error this function is called with parameter value false.

Usage:
<pre>
this.ajaxcall( '/mygame/mygame/myaction.html', { lock: true,
arg1: myarg1,
arg2: myarg2,
...
}, this, function( result ) {
// Do some stuff after a successful call
// NB : usually not needed as changes must be handled by notifications
// You should NOT modify the interface in a callback or it will most likely break the framework replays (or make it inaccurate)
// You should NOT make another ajaxcall in a callback in order not to create race conditions
} );
</pre>

Note: to reduce the boilerplate code you can define your own wrapper, which will do checking, locking and allow to skip parameters, for example
<pre>
ajaxcallwrapper: function(action, args, handler) {
if (!args) {
args = [];
}
args.lock = true;

if (this.checkAction(action)) {
this.ajaxcall("/" + this.game_name + "/" + this.game_name + "/" + action + ".html", args,//
this, (result) => { }, handler);
}
},
</pre>
This can be called like this which is a lot more compact
<pre>
this.ajaxcallwrapper('playDraw');
this.ajaxcallwrapper('playMove', {card: id})
</pre>

'''this.isInterfaceLocked()'''

When using "lock: true" in ajax call you can use this function to check if interface is in lock state (it will be locked during server call and notification processing).
This check can be used to block some other interactions which do not result in ajaxcall or if you want to suppress errors.

'''this.addActionButton( id, label, method, (opt)destination, (opt)blinking, (opt)color )'''

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

Arguments:
* id: an element 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.
* destination (optional): deprecated, do not use this. Use '''null''' as value if you need to specify other arguments.
* blinking (optional): if set to '''true''', the button is going blink to catch player's attention. Please don't abuse of blinking button.
* color: could be '''blue''' (default), '''red''' or '''gray'''.

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

<pre>
onUpdateActionButtons: function( stateName, args ) {

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.

Example using blinking red button:
<pre>
this.addActionButton( 'commit_button', _('Confirm'), 'onConfirm', null, true, 'red');
</pre>

Note: at least in studio example above will make button huge, because it sets it display of blinking things to '''block''',
if you don't like it you have to change css display value
of the button to inline-block (the id of the button is the first argument, i.e 'commit_button' in example above)

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

-----

It is also possible to control the delay timing dynamically (e.g., using notification args). As an example, maybe your notification 'cardPlayed' should pause for a different amount of time depending on the number or type of cards played.

For this case, use '''setSynchronous''' without specifying the duration and use '''setSynchronousDuration''' within the notification callback.

* NOTE: If you forget to invoke '''setSynchronousDuration''', the game will remain paused forever!

<pre>
setupNotifications: function () {
dojo.subscribe( 'cardPlayed', this, 'notif_cardPlayed' );
this.notifqueue.setSynchronous( 'cardPlayed' ); // wait time is dynamic
...
},

notif_cardPlayed: function (notif) {
// MUST call setSynchronousDuration

// Example 1: From notification args (PHP)
this.notifqueue.setSynchronousDuration(notif.args.duration);
...

// Or, example 2: Match the duration to a Dojo animation
var anim = dojo.fx.combine([
...
]);
anim.play();
this.notifqueue.setSynchronousDuration(anim.duration);
},
</pre>

=== Ignoring notifications ===
Sometimes you need to ignore some notification on client side. You don't want them to be shown in game log and you don't want them to be handled.

The most common use case is when a player gets private information. They will receive a specific notification (such as "You received Ace of Heart"), while other players would receive more generic notification ("Player received a card").

In X.game.php
<pre>
$this->notifyAllPlayers("dealCard", clienttranslate('${player_name} received a card'), [
'player_id' => $playerId,
'player_name' => $this->getActivePlayerName()
]);

$this->notifyPlayer($playerId, "dealCardPrivate", clienttranslate('You received ${cardName}'), [
"type" => $card["type"],
"cardName" => $this->getCardName($card["type"])
]);
</pre>

The problem with this approach is that the active player will receive two notifications:
* Player1 received a card
* You received Ace of Hearts

Hence, notification ignoring. Similar to setting a synchronous notification above, you can set up a check whether a notification should be ignored:
<pre>
this.notifqueue.setIgnoreNotificationCheck( 'dealCard', (notif) => (notif.args.player_id == this.player_id) );
</pre>

'''setIgnoreNotificationCheck(notificationId, predicate)'''
This method will set a check whether any of notifications of specific type should be ignored.

The parameters are:
* notificationId: before dispatching any notification of this type, the framework will call predicate to check whether notification should be ignored
* predicate (notif => boolean): a function that will receive notif object and will return true if this specific notification should be ignored

NOTE: You can think that it could be possible to send generic notification to all other players with notifyAllPlayers and it will seem to work. The problem is that table spectators would miss this notification and their user interface (and game log) wouldn't be updated.

IMPORTANT: Remember that this notification is ignored on the client side, but was still received by the client. Therefore it shouldn't contain any private information as cheaters can get it. In other words this is not a way to hide information.

IMPORTANT: When a game is reloaded with F5 or when opening a turn based game, old notifications are replayed as history notification. They are used just to update the game log and are stripped of all arguments except player_id, i18n and any argument present in message. If you use and other argument in your predicate you should preserve it as explained [[Main_game_logic:_yourgamename.game.php#Notify_players|here]].

=== Pre-defined notification types ===

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

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

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

'''simplePause''' - This notification will just delay other notifications, maybe useful if you know you need some extra time for animation or something. Requires a time parameter.

<pre>
self::notifyAllPlayers( 'simplePause', '', [ 'time' => 500] ); // time is in milliseconds
</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 should 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 browsers (see [[BGA_Studio_Guidelines|Guidelines]]).

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

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

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

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

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

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

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

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

IMPORTANT: all concerned nodes must have IDs to get tooltips

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

Remove a tooltip from the DOM node.

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

=== Warning messages ===

Sometimes, there is something important that is happening in 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 fulfills one of the end of the game conditions, 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 the current player.

* "msg" is the string to display. It should be translated.
* "type" can be set to "info", "error", or "only_to_log". 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. If set to "only_to_log", the message will be added to the game log but will not popup at the top of the screen.

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

'''confirmationDialog( message, yesHandler, noHandler )'''

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 bake the pie?'), dojo.hitch( this, function() {
this.bakeThePie();
} ) );
return; // nothing should be called or done after calling this, all action must be done in the handler
</pre>

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

=== Dialogs ===

As a general rule, you shouldn't use dialogs windows.

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

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

// Create the new dialog over the play zone. You should store the handler in a member variable to access it later
this.myDlg = new ebg.popindialog();
this.myDlg.create( 'myDialogUniqueId' );
this.myDlg.setTitle( _("my dialog title to translate") );
this.myDlg.setMaxWidth( 500 ); // Optional

// 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.setContent( html ); // Must be set before calling show() so that the size of the content is defined before positioning the dialog
this.myDlg.show();

// Now that the dialog has been displayed, you can connect your method to some dialog elements
// Example, if you have an "OK" button in the HTML of your dialog:
dojo.connect( $('my_ok_button'), 'onclick', this, function(evt){
evt.preventDefault();
this.myDlg.destroy();
} );

If necessary, you can remove the default top right corner 'close' icon, or replace the function called when it is clicked:
// Removes the default close icon
this.myDlg.hideCloseIcon();

// Replace the function call when it's clicked
this.myDlg.replaceCloseCallback( function() { ... } );

=== 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" => clienttranslate("a string with an ${argument}"), "args" => array( 'argument' => 'argument_value' ) ) ),
array( "four", "five", "six" ),
array( "seven", "height", "nine" )
);
</pre>

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

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

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

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

=== Scoring animated display ===

Sometimes (Terra Mystica final scoring for example), you may want to display a score value over an element to make the scoring easier to follow for the players.
You can do it with:

<pre>
this.displayScoring( anchor_id, color, score, duration, offset_x, offset_y );
</pre>

'''anchor_id''': ID of the element to place the animated score onto (without the '#')

'''color''': hexadecimal RGB representation of the color (should be the color of the scoring player), but without a leading '#'. For instance, 'ff0000' for red.

'''score''': numeric score to display, prefixed by a '+'

'''duration''': animation duration in milliseconds

'''offset_x''' and '''offset_y''': if both offset_x and offset_y are defined and not null, apply the following offset (in pixels) to the scoring animation. Note that the score is centered in the anchor, so the offsets might have to be negative if you calculate the position.

Note: if you want to display successively each score, you can use ''this.notifqueue.setSynchronous()'' function.

=== Speech bubble ===

For better interactivity in some games (Love Letter for example), you may use comic book style speech bubbles to express the players voices.
This is done with:

<pre>
this.showBubble(anchor_id, text, delay, duration, custom_class)
</pre>

text - what to put in bubble, can be html actually not just text

delay - in milliseconds is optional (default 0)

duration - in milliseconds is optional (default 3000)

custom_class - extra class to add to bubble is optional, if you need to override the default bubble style

'''Warning''': if your bubble could overlap other active elements of the interface (buttons in particular), as it stays in place even after disappearing, you should use a custom class to give it the style "pointer-events: none;" in order to intercept click events.

Note: If you want this visually, but want to take complete control over this bubble and its animation (for example to make it permanent) you can just use div with 'discussion_bubble' class on it, and content of div is what will be shown.

== Update players score ==

The column player_score from the player table is automatically loaded into this.scoreCtrl and therefore into the stars location on the player board. This occurs sometime after the <gamename>.js setup() function. However this score must be updated as the game progresses through player notifications (notifs).

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>

Set a player score to a specific value with animation :

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

Typical usage would be (that will process 'score' notification):
<pre>
setupNotifications : function() {
...
dojo.subscribe('score', this, "notif_score");
},
notif_score: function(notif) {
this.scoreCtrl[notif.args.player_id].setValue(notif.args.player_score);
},
</pre>

== Players panels ==

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Enable a player panel that has been disabled before.

'''this.enableAllPlayerPanels()'''

Enable all player panels that has been disabled before.

== Image loading ==

See also [[Game_art:_img_directory]].

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

'''dontPreloadImage( image_file_name )'''

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

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

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

Another example of use: in "Gosu" game with Kamakor extension, you play with 5 sets of cards among 10 available. Cards images are organized by sets, and we only preload the images corresponding to the 5 current sets with '''ensureSpecificGameImageLoading( image_file_names_array )'''.
<pre>
// By default, do not preload anything
this.dontPreloadImage( 'cards.png' );
this.dontPreloadImage( 'clan1.png' );
this.dontPreloadImage( 'clan2.png' );
this.dontPreloadImage( 'clan3.png' );
this.dontPreloadImage( 'clan4.png' );
this.dontPreloadImage( 'clan5.png' );
this.dontPreloadImage( 'clan6.png' );
this.dontPreloadImage( 'clan7.png' );
this.dontPreloadImage( 'clan8.png' );
this.dontPreloadImage( 'clan9.png' );
this.dontPreloadImage( 'clan10.png' );
var to_preload = [];
for( i in this.gamedatas.clans )
{
var clan_id = this.gamedatas.clans[i];
to_preload.push( 'clan'+clan_id+'.png' );
}
if( to_preload.length == 5 )
{
this.ensureSpecificGameImageLoading( to_preload );
}
</pre>

'''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 ensure that the "this" object will be set when the callback is called.

NOTE: In modern JS there are lambdas that eliminate need for that, the example above will look like this
<pre>
this.confirmationDialog( _('Are you sure you want to make this?'), () => {
this.ajaxcall( '/mygame/mygame/makeThis.html', { lock:true }, this, (result) => {} );
} );
</pre>

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

;'''onScreenWidthChange()'''
:This function can be overridden in your game to manage some resizing on the client side when the browser window is resized. This function is also triggered at load time, so it can be used to adapt to the :viewport size at the start of the game too.

;'''updatePageTitle()'''
:This function allows to update the current page title and turn description according to the game state. If the current game state description this.gamedatas.gamestate.descriptionmyturn is modified before :calling the function, it allows to update the turn description without changing state.

Example from Terra Mystica:
<pre>
onClickFavorTile: function( evt ) {
...
if ( ... ) {
this.gamedatas.gamestate.descriptionmyturn = _('Special action: ') + _('Advance 1 space on a Cult track');
this.updatePageTitle();
this.removeActionButtons();
this.addActionButton( ... );
...
return;
}
...

}
</pre>

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

== BGA Buttons ==

You can create a custom button, but the BGA framework provides a standard button that requires only .css classes: '''bgabutton''' and '''bgabutton_${color}'''.

'''Examples:'''

<pre>
<a href="#" id="my_button_id" class="bgabutton bgabutton_blue"><span>My blue button</span></a>
</pre>
<pre>
<a href="#" id="my_button_id" class="bgabutton bgabutton_gray"><span>My gray button</span></a>
</pre>
<pre>
<a href="#" id="my_button_id" class="bgabutton bgabutton_red"><span>My red button</span></a>
</pre>
<pre>
<a href="#" id="my_button_id" class="bgabutton bgabutton_red bgabutton_big"><span>My big red button</span></a>
</pre>

'''Note''': To see it in action, check out ''Coloretto''.

'''Disabling:'''
You can disable the '''bgabutton''' by adding the css class '''disabled''' in you js. The disabled button is still visible but is grey and not clickable.
For example in the '''onUpdateActionButtons''' :
<pre>this.addActionButton( 'play_button_id', _('Play 1 to 3 cards'), 'playFunctionButton', null, false, 'blue' ); //Create a blue button
if (Condition == true)
{
dojo.addClass( 'play_button_id', 'disabled');//disable the button
}</pre>

== Sounds ==

Add a custom sound and make it load with your interface:

Add this in your template (.tpl) file:
<pre>
<audio id="audiosrc_<gamename>_<yoursoundname>" src="{GAMETHEMEURL}img/<gamename>_<yoursoundname>.mp3" preload="none" autobuffer></audio>
<audio id="audiosrc_o_<gamename>_<yoursoundname>" src="{GAMETHEMEURL}img/<gamename>_<yoursoundname>.ogg" preload="none" autobuffer></audio>
</pre>

Note: this is a requirement to provide both a mp3 and a ogg file.

Play the sound (from your .js file):

<pre>
playSound('<gamename>_<yoursoundname>');
</pre>

Disable the standard "move" sound for this move (to replace it with your custom sound):

Add this to your notification handler:

<pre>
this.disableNextMoveSound();
</pre>

Note: it only disable the sound for the next move.

Gamehelphex

2021-05-25T04:34:29Z

User Already Exists: Copy-editing, updated Hex terminology

===INTRODUCTION===

The game of Hex was invented and popularized in Denmark by Piet Hein in 1942, and later independently discovered by John Nash in 1947. The game is attractive because it has extremely simple rules, yet a surprising amount of strategic depth. Another interesting aspect is that the game can't end in a tie.

===GOAL===

The board has two red edges and two blue edges. Each player's goal is to connect their two edges by stones of their color.

===TURNS===

The players alternately place a stone of their own color on the board, with Red going first. A stone can be placed on any empty cell. Once placed, stones are never moved or removed.

===THE SWAP RULE===

To make sure the first player does not have an unfair advantage, the swap rule is used. After the first player opens with a red stone, the second player can either
* continue to play normally, by placing a blue stone, or
* decide to switch colors. In that case, the second player becomes Red, the first player becomes Blue, and the first move is kept. After this, the game continues normally, i.e., it is the first player's turn to play a blue stone.

Alternatively, the swap rule can also be implemented in such a way that the players keep their original colors. In that case, if Blue wants to swap, Red's initial stone is replaced by a blue stone and mirrored about the long diagonal. After this, it is Red's turn.

===GAME END===

The game ends when one of the players has connected their edges with a path of stones of their color. The game can't end in a tie. It is customary for the losing player to resign when it is clear to both players who will win.

===BOARD SIZES===

The game can be played on boards of several different sizes. The 6x6 board is designed to help beginners understand the basic rules and discover simple game patterns. The 11x11 board is a more classic size and was used by Piet Hein. The 13x13 board is preferred by many experts. The 14x14 board is the one recommended by John Nash, and the 15x15 board allows even longer plays.

Game art: img directory

2021-05-18T23:46:55Z

User Already Exists: /* Images naming constraints */ typo

{{Studio_Framework_Navigation}}

== Requested images ==

The following images are requested by BGA:

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

;game_box180.png
;game_box75.png

* Don't modify these images, they are auto generated by "Reload game box image" action. If you have another copy of your source make sure you update you copy of these files after they have been generated and not override with old copied.

;game_icon.png

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

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

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

;game_banner.jpg
* size 1386x400px
* should not contain any text; representative of the atmosphere of the game such as a cover element or communication image; the box image covering the banner on the left should stand out

;game_displayX.jpg (X an integer between 0 and 9)
* height between 400px and 760px, width maximum 1.5 x height;
* the idea is to make players want to play the game, so it could be a zoomed card, some detail of the board, an overview of an ongoing physical game... but NOT a screenshot of the BGA adaptation since there is already the "see game in action" replay for that

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

== Game art ==

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

=== Images naming constraints ===

To be correctly deployed your images file names should not contain spaces or parentheses.

=== Images loading ===

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

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

General recommendation it to have no more than dozen of image files, 2Mb max each. However if there is heavy game resources specific to a player (i.e. player board of specific color or set of cards) it is better to separate them and "don't pre-load" since in any given game only some of them will be used.

=== Images format ===

You can use these image formats while building your game interface:
;jpg images

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

;png images

should be used for images with transparency, such as non-square tokens, meeples, etc (combined into sprite).

;gif images

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

;svg images

svg images can be really efficient for icons or abstract images

=== Use background-size ===

In order to allow for players to use the browser zoom without your images becoming pixelated, it's recommended to use higher resolution images than needed for the normal display of your interface, and to use the css property '''background-size''' to fit the image to the size you need for your interface.

=== Use CSS Sprites ===

To limit the number of images load and make the game load faster, you must use CSS sprites, i.e. you must gather several images in a single one. However, there are limitations. Do not make any CSS image sprite with dimensions that exceed 4096x4096 pixels or it will not work on mobile devices (Android max texture size is 4096 pixels, test your own browser at [http://webglreport.com/ WebGL Report]).

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

'''Important:''' the maximum image size should be 4096x4096 (otherwise, some devices may not display parts of the image, see https://stackoverflow.com/questions/34682482/what-is-the-maximum-sprite-sheet-size-i-can-use-for-android-devices)

Tools:
* Sprite Generator https://www.toptal.com/developers/css/sprite-generator/

=== Shrink images ===

If you get high resolution images from publisher you need to shrink them since web display requires much lower resolution than printing.

* Shrink images without loss of quality https://tinypng.com/ or http://www.iloveimg.com/

== Image Manipulation Tools ==

You have no choice but to use one of the image manipulating tools to create a successful game adaptation, you would have to
deal with
* Converting to supported formats
* Adding transparency
* Stitching
* Shrinking with no quality loss
* Resizing

For that you need a good tools, recommended tools (if you know more add them here)
* Gimp (all platforms) - general GUI image editor
* Paint.net (Windows) - general GUI image editor
* ImageMagic (All platforms) - https://www.imagemagick.org/script/download.php - command line image editor, great for mass manipulations and scripting