Board Game Arena - User contributions [en]

Gamehelpmedina

2021-02-03T13:48:12Z

Bdrieu:

== Introduction ==

In Medina, players must place two pieces on the board (except when allowed to skip this with a tea tile), either augmenting an existing building (or starting a new building if the current building of that color is finished), or expanding one of the other features of the city, like the market or the walls. Each player will claim one building of each of the four colors by the end of the game, giving one point per wooden piece attached to the building.

Also, if you own the largest building of a particular color you get a bonus for that color. Finally, there are bonuses for palaces around the well, as well as for the player who most recently connected one of their buildings to the walls, which grow from the four corners of the city.

== Setup ==

Depending on edition selected and players number, each player receives a number of blocks that they will place on the board in turn.

A merchant is placed randomly on the board as well as a well if applicable.

A first player is randomly chosen.

== Blocks ==

=== Buildings ===
These are the blocks received in the largest quantity. They come in four colors: white, purple, maroon, orange.

Adjacent buildings constitutes palaces, which grow in time. A building can be placed only adjacent orthogonally to an unfinished palace of this color or anywhere on the board if no palace of this color is unfinished.

Buildings cannot be placed adjacent orthogonally or diagonally to another palace, meaning there is always room for an alley between two palaces.

=== Rooftops ===
Rooftops are used to claim palaces. A player can only claim ONE palace of a given color. Once they have placed a rooftop on a palace, this palace is finished and cannot be expanded further by buildings.

Also, if a player claims the largest palace they will get the palace tile of this color for additional points. Palace tiles can change hands several times.

In 2nd edition game, players will also receive neutral rooftops used to finish palaces and thwart opponents plans. Palace tiles can be claimed by the "neutral" player and be placed back onto the board.

=== Stables ===
Stables can be used only to expand existing palaces. They must be placed orthogonally adjacent to a palace (finished or not). As buildings, they must not be placed orthogonally or diagonally to another palace.

=== Walls ===
Walls are placed next to a tower (there is one on each corner of the board) or to another wall. Chains of walls are then created from each corner, but corners must be separated by an empty places (a gate) between the chains of walls.

When a wall is placed orthogonally adjacent to a finished palace (including stables), the owning player receives a watcher tile for additional points. Also, when a finished palace is expanded with a stable to connect to an already existing wall, the owner player receives a watcher tile.

Neutral player can claim watcher tiles.

=== Merchants ===
Merchants can only be placed next to an existing merchant in order to create a string of merchants (the market). A merchant can only be placed orthogonally to one and ONLY one existing merchant in either ends of the market. If both ends of the market are blocked, new merchants can be placed anywhere save adjacent to existing merchants, creating a new market.

=== Tea tiles ===
If applicable, the first players to claim purple palace will receive tea tiles. Playing a tea tile will allow a player to pass by clicking on it in their inventory. It is not possible to pass twice in a turn.

Neutral player can claim tea tiles (which are removed from play).

== End game and scoring ==
When a player is unable to play they passe until they can play again. When all players are unable to play, game ends and the winner is the player with the most points. Points are awarded as follows:

* each building or stable constituting a palace: 1 point
* each wall adjacent to a palace: 1 point
* each merchant adjacent to a palace: 1 point (NOT counted double it adjacent to two or more buildings)
* each palace orthogonally separated two spaces away from the well (see water icons): 4 points
* each palace tile: 1-4 points
* each watcher tile: 1-4 point

In case of ties, the player with the largest palace wins. In case of another tie, the player owning the largest palace that has been claimed first wins.

== Differences between editions ==
There are significant differences between the two editions of the game.

=== Well ===
In second edition, a palace that has a building or stable that is separated orthogonally by one space from the well grants four more points to its owner.

This can be setup in a 1st edition game if the "well" option is selected (by default).

=== Merchants on watcher tiles ===
In second edition, merchants are placed on watcher tiles. The first player to claim a watcher also receives the merchants. If the neutral player claims this watcher tile, the merchants are removed from play.

This can be setup in a 1st edition game if the "merchant on watchers" option is selected.

=== Tea tiles ===
In second edition, the first players to claim purple palaces will receive tea tiles (3, then 2, then 1). Playing a tea tile will allow a player to pass by clicking on it in their inventory. It is not possible to pass twice in a turn.

This can be setup in a 1st edition game if the "tea tiles" option is selected.

=== Last player with rooftops ===
In first edition, if there is only one player with rooftops left they MUST play at least one rooftop each turn if possible. The game will refuse to finish a turn if that constraint is not satisfied. Once this player does not have rooftops anymore, they can still continue to play normally.

=== First turn ===
In a second edition game, the first player of a two players game only plays one block in their first turn (and also the second player in a three or four players game).

This is not the case in the first edition.

=== Neutral roofs ===
In a first edition game, there is no neutral roof and hence no neutral player to claim tiles.

=== Number of blocks ===
In a first and second edition game, the number of blocks received during game setup is different.

Gamehelpmedina

2021-01-27T15:23:58Z

Bdrieu:

== Introduction ==

In Medina, players must place two pieces on the board (except when allowed to skip this with a tea tile), either augmenting an existing building (or starting a new building if the current building of that color is finished), or expanding one of the other features of the city, like the market or the walls. Each player will claim one building of each of the four colors by the end of the game, giving one point per wooden piece attached to the building.

Also, if you own the largest building of a particular color you get a bonus for that color. Finally, there are bonuses for palaces around the well, as well as for the player who most recently connected one of their buildings to the walls, which grow from the four corners of the city.

== Setup ==

Depending on edition selected and players number, each player receives a number of blocks that they will place on the board in turn.

A merchant is placed randomly on the board as well as a well if applicable.

A first player is randomly chosen.

== Blocks ==

=== Buildings ===
These are the blocks received in the largest quantity. They come in four colors: white, purple, maroon, orange.

Adjacent buildings constitutes palaces, which grow in time. A building can be placed only adjacent orthogonally to an unfinished palace of this color or anywhere on the board if no palace of this color is unfinished.

Buildings cannot be placed adjacent orthogonally or diagonally to another palace, meaning there is always room for an alley between two palaces.

=== Rooftops ===
Rooftops are used to claim palaces. A player can only claim ONE palace of a given color. Once they have placed a rooftop on a palace, this palace is finished and cannot be expanded further by buildings.

Also, if a player claims the largest palace they will get the palace tile of this color for additional points. Palace tiles can change hands several times.

In 2nd edition game, players will also receive neutral rooftops used to finish palaces and thwart opponents plans. Palace tiles can be claimed by the "neutral" player and be placed back onto the board.

=== Stables ===
Stables can be used only to expand existing palaces. They must be placed orthogonally adjacent to a palace (finished or not). As buildings, they must not be placed orthogonally or diagonally to another palace.

=== Walls ===
Walls are placed next to a tower (there is one on each corner of the board) or to another wall. Chains of walls are then created from each corner, but corners must be separated by an empty places (a gate) between the chains of walls.

When a wall is placed orthogonally adjacent to a finished palace (including stables), the owning player receives a watcher tile for additional points. Also, when a finished palace is expanded with a stable to connect to an already existing wall, the owner player receives a watcher tile.

Neutral player can claim watcher tiles.

=== Merchants ===
Merchants can only be placed next to an existing merchant in order to create a string of merchants (the market). A merchant can only be placed orthogonally to one and ONLY one existing merchant in either ends of the market. If both ends of the market are blocked, new merchants can be placed anywhere save adjacent to existing merchants, creating a new market.

=== Tea tiles ===
If applicable, the first players to claim purple palace will receive tea tiles. Playing a tea tile will allow a player to pass by clicking on it in their inventory. It is not possible to pass twice in a turn.

Neutral player can claim tea tiles (which are removed from play).

== End game and scoring ==
When a player is unable to play he is eliminated from future turns. When all players are unable to play, game ends and the winner is the player with the most points. Points are awarded as follows:

* each building or stable constituting a palace: 1 point
* each wall adjacent to a palace: 1 point
* each merchant adjacent to a palace: 1 point (NOT counted double it adjacent to two or more buildings)
* each palace orthogonally separated two spaces away from the well (see water icons): 4 points
* each palace tile: 1-4 points
* each watcher tile: 1-4 point

In case of ties, the player with the largest palace wins. In case of another tie, the player owning the largest palace that has been claimed first wins.

== Differences between editions ==
There are significant differences between the two editions of the game.

=== Well ===
In second edition, a palace that has a building or stable that is separated orthogonally by one space from the well grants four more points to its owner.

This can be setup in a 1st edition game if the "well" option is selected (by default).

=== Merchants on watcher tiles ===
In second edition, merchants are placed on watcher tiles. The first player to claim a watcher also receives the merchants. If the neutral player claims this watcher tile, the merchants are removed from play.

This can be setup in a 1st edition game if the "merchant on watchers" option is selected.

=== Tea tiles ===
In second edition, the first players to claim purple palaces will receive tea tiles (3, then 2, then 1). Playing a tea tile will allow a player to pass by clicking on it in their inventory. It is not possible to pass twice in a turn.

This can be setup in a 1st edition game if the "tea tiles" option is selected.

=== Last player with rooftops ===
In first edition, if there is only one player with rooftops left they MUST play at least one rooftop each turn if possible. The game will refuse to finish a turn if that constraint is not satisfied. Once this player does not have rooftops anymore, they can still continue to play normally.

=== First turn ===
In a second edition game, the first player of a two players game only plays one block in their first turn (and also the second player in a three or four players game).

This is not the case in the first edition.

=== Neutral roofs ===
In a first edition game, there is no neutral roof and hence no neutral player to claim tiles.

=== Number of blocks ===
In a first and second edition game, the number of blocks received during game setup is different.

Gamehelpmedina

2021-01-26T21:58:19Z

Bdrieu:

== Introduction ==

In Medina, players must place two pieces on the board (except when allowed to skip this with a tea tile), either augmenting an existing building (or starting a new building if the current building of that color is finished), or expanding one of the other features of the city, like the market or the walls. Each player will claim one building of each of the four colors by the end of the game, giving one point per wooden piece attached to the building.

Also, if you own the largest building of a particular color you get a bonus for that color. Finally, there are bonuses for palaces around the well, as well as for the player who most recently connected one of their buildings to the walls, which grow from the four corners of the city.

== Setup ==

Depending on edition selected and players number, each player receives a number of blocks that they will place on the board in turn.

A merchant is placed randomly on the board as well as a well if applicable.

A first player is randomly chosen.

== Blocks ==

=== Buildings ===
These are the blocks received in the largest quantity. They come in four colors: white, purple, maroon, orange.

Adjacent buildings constitutes palaces, which grow in time. A building can be placed only adjacent orthogonally to an unfinished palace of this color or anywhere on the board if no palace of this color is unfinished.

Buildings cannot be placed adjacent orthogonally or diagonally to another palace, meaning there is always room for an alley between two palaces.

=== Rooftops ===
Rooftops are used to claim palaces. A player can only claim ONE palace of a given color. Once they have placed a rooftop on a palace, this palace is finished and cannot be expanded further by buildings.

Also, if a player claims the largest palace they will get the palace tile of this color for additional points. Palace tiles can change hands several times.

In 2nd edition game, players will also receive neutral rooftops used to finish palaces and thwart opponents plans. Palace tiles can be claimed by the "neutral" player and be placed back onto the board.

=== Stables ===
Stables can be used only to expand existing palaces. They must be placed orthogonally adjacent to a palace (finished or not). As buildings, they must not be placed orthogonally or diagonally to another palace.

=== Walls ===
Walls are placed next to a tower (there is one on each corner of the board) or to another wall. Chains of walls are then created from each corner, but corners must be separated by an empty places (a gate) between the chains of walls.

When a wall is placed orthogonally adjacent to a finished palace (including stables), the owning player receives a watcher tile for additional points. Also, when a finished palace is expanded with a stable to connect to an already existing wall, the owner player receives a watcher tile.

Neutral player can claim watcher tiles.

=== Merchants ===
Merchants can only be placed next to an existing merchant in order to create a string of merchants (the market). A merchant can only be placed orthogonally to one and ONLY one existing merchant in either ends of the market. If both ends of the market are blocked, new merchants can be placed anywhere save adjacent to existing merchants, creating a new market.

=== Tea tiles ===
If applicable, the first players to claim purple palace will receive tea tiles. Playing a tea tile will allow a player to pass by clicking on it in their inventory. It is not possible to pass twice in a turn.

Neutral player can claim tea tiles (which are removed from play).

== End game and scoring ==
When a player is unable to play he is eliminated from future turns. When all players are unable to play, game ends and the winner is the player with the most points. Points are awarded as follows:

* each building or stable constituting a palace: 1 point
* each wall adjacent to a palace: 1 point
* each merchant adjacent to a palace: 1 point (NOT counted double it adjacent to two or more buildings)
* each palace orthogonally separated two spaces away from the well (see water icons): 4 points
* each palace tile: 1-4 points
* each watcher tile: 1-4 point

In case of ties, the player with the largest palace wins. In case of another tie, the player owning the largest palace that has been claimed first wins.

== Differences between editions ==
There are significant differences between the two editions of the game.

=== Well ===
In second edition, a palace that has a building or stable that is separated orthogonally by one space from the well grants four more points to its owner.

This can be setup in a 1st edition game if the "well" option is selected (by default).

=== Merchants on watcher tiles ===
In second edition, merchants are placed on watcher tiles. The first player to claim a watcher also receives the merchants. If the neutral player claims this watcher tile, the merchants are removed from play.

This can be setup in a 1st edition game if the "merchant on watchers" option is selected.

=== Tea tiles ===
In second edition, the first players to claim purple palaces will receive tea tiles (3, then 2, then 1). Playing a tea tile will allow a player to pass by clicking on it in their inventory. It is not possible to pass twice in a turn.

This can be setup in a 1st edition game if the "tea tiles" option is selected.

=== Last remaining player ===
In first edition, if there is only one player able to play, they MUST play at least one rooftop each turn if possible. The game will refuse to finish a turn if that constraint is not satisfied. Once this player does not have rooftops anymore, they can still continue to play normally.

=== First turn ===
In a second edition game, the first player of a two players game only plays one block in their first turn (and also the second player in a three or four players game).

This is not the case in the first edition.

=== Neutral roofs ===
In a first edition game, there is no neutral roof and hence no neutral player to claim tiles.

=== Number of blocks ===
In a first and second edition game, the number of blocks received during game setup is different.

Gamehelpmedina

2021-01-26T21:43:09Z

Bdrieu: Created this page.

== Introduction ==

In Medina, each turn, players must place two pieces on the board (except when allowed to skip this with a tea tile), either augmenting an existing building (or starting a new building if the current building of that color is finished), or expanding one of the other features of the city, like the market or the walls. Each player will claim one building of each of the four colors by the end of the game, giving one point per wooden piece attached to the building.

Also, if you own the largest building of a particular color you get a bonus for that color. Finally, there are bonuses for palaces around the well, as well as for the player who most recently connected one of their buildings to the walls, which grow from the four corners of the city.

== Setup ==

Depending on edition selected and players number, each player receives a number of blocks that they will place on the board in turn.

A merchant is placed randomly on the board as well as a well if applicable.

A first player is randomly chosen.

== Blocks ==

=== Buildings ===

These are the blocks received in the largest quantity. They come in four colors: white, purple, maroon, orange.

Adjacent buildings constitutes palace, which grow in time. A building can be placed only adjacent orthogonally to an unfinished palace of this color or anywhere on the board if no palace of this color is unfinished.

Buildings cannot be placed adjacent orthogonally or diagonally to another palace, meaning there is always room for an alley between to palaces.

=== Rooftops ===

Rooftops are used to claim palaces. A player can only claim ONE palace of a color. Once they have placed a rooftop on a palace, this palace is finished cannot be expanded further by buildings.

Also, if a player claims the largest palace they will get the palace tile of this color for additional points.

In 2nd edition game, players will also receive neutral rooftops used to finish palaces and thwarts opponents plans. Neutral players can claim palace tiles.

=== Stables ===

Stables can be used only to expand existing palaces. They must be placed orthogonally adjacent to a palace (finished or not). As buildings, they must not be placed orthogonally or diagonally to another palace.

=== Walls ===

Walls are placed next to a tower (there is one on each corner of the board) or to another wall. Chains of walls are then created from each corner, but corners must be separated by an empty places (a gate) between the chains of walls.

When a wall is placed orthogonally adjacent to a finished palace (including stables), the owning player receives a watcher tile for additional points. Also, when a finished palace is expanded with a stable to connect to an already existing wall, the owner player receives a watcher tile. Neutral player can claim watcher tiles.

=== Merchants ===

Merchants can only be placed next to a merchant in order to create a string of merchants (the market). A merchant can only be placed orthogonally to one and ONLY one merchant in either ends of the market. If both ends of the market are blocked, new merchants can be placed anywhere save adjacent to existing merchants.

=== Tea tiles ===

If applicable, the first players to claim purple palace will receive tea tiles. Playing a tea tile will allow a player to pass by clicking on it in their inventory. It is not possible to pass twice in a turn.

Neutral player can claim tea tiles (which are removed from play).

== End game and scoring ==

When a player is unable to play he is eliminated from future turns. When all players are unable to play, game ends and the winner is the player with the most points. Points are awarded as follows:

* each building or stable constituting a palace: 1 point
* each wall adjacent to a palace: 1 point
* each merchant adjacent to a palace: 1 point (NOT counted double it adjacent to two or more buildings)
* each palace orthogonally separated two spaces away from the well (see water icons): 4 points
* each palace tile: 1-4 points
* each watcher tile: 1-4 point

In case of ties, the player with the largest palace wins. In case of a remaining tie, the player with largest palace that has been claimed first wins.

== Differences between editions ==

There are significative differences between the two editions of the game.

=== Well ===

In second edition, a palace that has a building or stable that is separated orthogonally by one space from the well grants four more points to its owner.

This can be setup in a 1st edition game if the "well" option is selected (by default).

=== Merchants on watcher tiles ===

In second edition, merchants are placed on watcher tiles. The first player to claim a watcher also receives the merchants. If the neutral player claims this watcher tile, the merchants are removed from play.

This can be setup in a 1st edition game if the "merchant on watchers" option is selected.

=== Tea tiles ===

In second edition, the first players to claim purple palace will receive tea tiles. Playing a tea tile will allow a player to pass by clicking on it in their inventory. It is not possible to pass twice in a turn.

This can be setup in a 1st edition game if the "tea tiles" option is selected.

=== Last remaining player ===

In first edition, if there is only one player able to play, they MUST play at least one rooftop each turn if possible. The game will refuse to finish a turn if that caonstraint is not satisfied. Once this player does not have rooftops anymore, they can still continue to play normally.

=== First turn ===

In a second edition game, in a two players game, the first player only plays one block in their first turn (and also the second player in a three or four players game).

This is not the case in the first edition.

=== Neutral roofs ===

In a first edition game, there is no neutral roof and hence no neutral player to claim tiles.

=== Number of blocks ===

In a first and second edition game, the number of blocks received during game setup is different.

Game interface logic: Game.js

2020-12-02T21:52:14Z

Bdrieu: Add parameters

{{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 instant replay mode (replay during the game)

; g_archive_mode
: Returns true if the game is in archive mode (advanced replay after the game has ended)

---

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 should not use the '''getElementById''' function.

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

'''dojo CSS classes manipulation'''

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>

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

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

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

See also full doc on dojo.place : [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]]".

'''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' );
</pre>

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

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

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

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

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

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

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

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

'''Rotating elements'''

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

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

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

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

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

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

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

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

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

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

Or you can use in-place handler

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

Note this function store connection halder (and this is the only real diffrence between this one and dojo.connect), if you planning on destroying the element you connected you MUST call this.disconnect() to prevent resource leaks.

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

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

this.connectClass('pet', 'onclick', 'onPet');

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

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

=== Pre-defined notification types ===

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

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

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

== Tooltips ==

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

Add a simple text tooltip to the DOM node.

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

You must specify both helpString and actionString. Most of the time, you 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 on the game and you have to make sure all players get the message. Most of the time, the evolution of the game situation or the game log is enough, but sometimes you need something more visible.

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

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

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

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

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

=== Confirmation dialog ===

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

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

Gamehelpdownforce

2020-09-29T14:05:19Z

Bdrieu: Add betting variants

Downforce is a card-driven bidding, racing, and betting game for 2-6 players based on Top Race, the award-winning design by the legendary Wolfgang Kramer. Players first bid to own the six cars in the race, then they play cards from their hand to speed them around the track. However, most cards will also move their opponents' cars. So figuring out just the right time to play a card is the key to victory. Along the way, players make secret bets on who they think will win the race. Whoever has the most money from their prize money, winning bets, and remaining bank wins.

== Start of the game ==

The game is composed of:

* a game board
* six colored cars (black, blue, green, yellow, orange, red)
* speed cards with one to six lines with a color and a speed on each
* six special speed cards with a single speed line
* power cards with special abilities

A race circuit is chosen and all six racing cars are placed randomly on starting spaces. Then, six color cards are shuffled and disposed on a stack. Each player takes an equal number of speed cards.

== Auctions ==

The first color card is then drawn and every player will secretly and simultaneously choose a card from their hand to auction on it. The highest speed line matching the current auction color will win the auction and get the car, the special speed card and a power card associated to the car if this game option has been selected.

When all auctions are processed, the race begin.

== Player's turn ==

During a player's turn, a player plays a speed card and moves in order every car that matches a speed line on it from top to bottom. Cars have to move as far as possible unless blocked by "traffic jams" and it is the current player that moves all cars, even opponents'. So it is possible (and advised!) to play opponents' car so bad they are stuck and cannot move.

If during a turn a car crosses a yellow line, all players must secretly bid on which car will win the race. Betting on the winner will provide additional points and sound bets can win a game even for the last of the race.

== End of the game ==

The game ends when all of the cars have crossed the finish line. Payouts are given to players according to their race results:

* '''winner of the race''': 12M$
* '''second''': 9M$
* '''third''': 6M$
* '''fourth''': 4M$
* '''fifth''': 2M$

Additionally, betting payouts are awarded as follows:

* '''first bet''':
** betting on the winner: 9M$
** betting on the second: 6M$
** betting on the third: 3M$
* '''second bet''':
** betting on the winner: 6M$
** betting on the second: 4M$
** betting on the third: 2M$
* '''third bet''':
** betting on the winner: 3M$
** betting on the second: 2M$
** betting on the third: 1M$

== Variants ==

=== Powers ===
Powers can be added into the game for additional complexity and more dynamic games. During each car auction, a power is attached to a car an the winner of the auction get the power. If a player has several powers, they must choose only one.

The base powers are the following:

* '''Aggressive''': If you play a card with your car at the top the the card, you may move that car 1 additional space
* '''Cunning''': You always move your cars, even on other player's turns
* '''Determined''': On any player's turn, if your car moved into only rectangular spaces, you may move it 2 additional spaces
* '''Strategic''': If you play a speed car with all six colors on it, you may ignore one color of it
* '''Tricky''': On your turn, you may move the cars in reverse order, from lower to highest
* '''Unpredictable''': If you play a card with a wild on it, you may use that wild for a color that is already on the card

If the "additional powers" option is selected, the powers from the ''Danger Circuit'' expansion are added into the game:

* '''Ambitious''': On any player's turn, if your car crosses a betting line you may move it 2 additional spaces
* '''Experienced''': On any player's turn, if any car starts its movement in a space directly ahead of your car, you may move your car into the space that car moved out of
* '''Tough''': On any player's turn, if your car ends its movement in a space adjacent to a rumble strip, you may move it 2 additional spaces
* '''Bold''': On your turn, if your car would move 1 or 2 spaces, move it 3 spaces instead
* '''Defensive''': If none of your cars move on your turn, move one of your cars 3 spaces
* '''Reckless''': On your turn, if your car moves through a Tight Space, you may move it 2 additional spaces

=== Betting variants ===

Two additional betting variants are provided:

* '''odds betting''': instead of normal betting payout, multiply the '''current''' ranking of the car you bet by the bet multiplied (×3,×2,×1 for the first bet, ×2,×1,×0 for the second and ×1,×0,×0 for the third). So if you bet on the winning car that was ranked #3 on the first bet, you collect 9M$! If you bet on the car that was first during second bet and that it ended second, you get 1M$.
* '''odds betting, winner only''': same as above but only the winning car provide payouts. This is an all-or-nothing scenario, but with high risk high reward.

== Race Tracks ==

There are 6 tracks for choosing in the game.

=== River Station and Marina Bay ===
There are normal boards with no special features.

=== Crosstown Speedway ===
This track features two crossover loops and two split sections. Cars entering the crossover loop must move into the loop. They cannot move directly from the entry to the exit directly or with a power.

=== Switchback Pass ===
This track features dangerous spaces which are too small to fit any cars and have cracks on them. They can only be used to pass another car. You cannot end your movement on it and you are forced to move back to a regular space if there is one.

=== Aloha Sands ===
This tracks features ramps which can be used to zoom ahead. They can only be used if the car has an equal or higher speed than the one on the ramp, has at least 1 space of movement remaining and the landing space is empty.

=== Savanna Stretch ===
This tracks features animals including antelope, elephant and python. They occuoy one space on the board and block any movement until passed by, then they will move to their next space.

Tips downforce

2020-06-16T15:28:20Z

Bdrieu: Created page with "== Auctioning == The cost of every car you buy is deducted to your balance. At the end of the game, the player with the most money wins, so choose your cars wisely! Do not..."

== Auctioning ==

The cost of every car you buy is deducted to your balance. At the end of the game, the player with the most money wins, so choose your cars wisely! Do not buy as many cars as possible because it would cose you too much. Do not buy your cars too expensive as well unless you really, really want one.

Before auctioning, ask yourself if your speed cards match the color of the car. You have no 6 or 5 speed lines matching this car? Perhaps this is not a good car for you?

== The race ==

When you play a card, you will most likely move the cars of the others. So do not hesitate to move them through long paths, do not hesitate to put them into position to be blocked next turn. Likewise, pay attention to where your cars are.

If you manage to be the first to reach a tight turn and block the other cars, then the other players will need to move your car in order to advance. And as speed lines are played from the quickest to the slowest, there are good chances that other players will be forced to play a good card on your car.

== The betting ==

Remember that you are not obliged to bid on your cars. So if you see that another player took the lead, you can still bid on them to get a consolation prize. Likewise, if you manage to take the lead, even temporarily and that other players bid on you, they have a good interest in making you win! So they will play good cards on you in order to maximize their bidding payouts. Oh joy!

Game interface logic: Game.js

2020-06-08T23:28:40Z

Bdrieu: /* Scoring animated display */ Add precisions

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

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

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

== ShrinkSafe minimization ==

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

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

== 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 should not use the '''getElementById''' function.

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

'''dojo CSS classes manipulation'''

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

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

values possibles :

"replace" : (see description above).

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

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

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

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

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

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

See also full doc on dojo.place : [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]]".

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

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

=== Animations ===

'''Dojo Animations'''

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

'''Rotating elements'''

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

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

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

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

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

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

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

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

Usage: checkAction: function( action, nomessage )

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

Restricted arguments names (please don't use them):

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

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

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

'''this.checkPossibleActions( "my_action_name" )'''

Usage: 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)

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

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

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

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

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

'''this.confirmationDialog()'''

Display a confirmation dialog with a yes/no choice.

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

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

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

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

'''this.addActionButton( id, label, method, (opt)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 Hears 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>

=== Pre-defined notification types ===

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

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

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

== Tooltips ==

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

Add a simple text tooltip to the DOM node.

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

You must specify both helpString and actionString. Most of the time, you 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 on the game and you have to make sure all players get the message. Most of the time, the evolution of the game situation or the game log is enough, but sometimes you need something more visible.

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

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

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

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

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

=== Confirmation dialog ===

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

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

delay in milliseconds is optional (default 0)

duration in milliseconds is optional (default 3000)

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

== Update players score ==

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

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

Set a player score to a specific value:

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

== Players panels ==

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Enable a player panel that has been disabled before.

'''this.enableAllPlayerPanels()'''

Enable all player panels that has been disabled before.

== Image loading ==

See also [[Game_art:_img_directory]].

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

'''dontPreloadImage( image_file_name )'''

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

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

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

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

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

== BGA GUI components ==

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

[[Studio#BGA_Studio_game_components_reference]]

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

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

Gamehelpdownforce

2020-05-25T09:28:20Z

Bdrieu: Created page with "Downforce is a card-driven bidding, racing, and betting game for 2-6 players based on Top Race, the award-winning design by the legendary Wolfgang Kramer. Players first bid to..."

Downforce is a card-driven bidding, racing, and betting game for 2-6 players based on Top Race, the award-winning design by the legendary Wolfgang Kramer. Players first bid to own the six cars in the race, then they play cards from their hand to speed them around the track. However, most cards will also move their opponents' cars. So figuring out just the right time to play a card is the key to victory. Along the way, players make secret bets on who they think will win the race. Whoever has the most money from their prize money, winning bets, and remaining bank wins.

== Start of the game ==

The game is composed of:

* a game board
* six colored cars (black, blue, green, yellow, orange, red)
* speed cards with one to six lines with a color and a speed on each
* six special speed cards with a single speed line
* power cards with special abilities

A race circuit is chosen and all six racing cars are placed randomly on starting spaces. Then, six color cards are shuffled and disposed on a stack. Each player takes an equal number of speed cards.

== Auctions ==

The first color card is then drawn and every player will secretly and simultaneously choose a card from their hand to auction on it. The highest speed line matching the current auction color will win the auction and get the car, the special speed card and a power card associated to the car if this game option has been selected.

When all auctions are processed, the race begin.

== Player's turn ==

During a player's turn, a player plays a speed card and moves in order every car that matches a speed line on it from top to bottom. Cars have to move as far as possible unless blocked by "traffic jams" and it is the current player that moves all cars, even opponents'. So it is possible (and advised!) to play opponents' car so bad they are stuck and cannot move.

If during a turn a car crosses a yellow line, all players must secretly bid on which car will win the race. Betting on the winner will provide additional points and sound bets can win a game even for the last of the race.

== End of the game ==

The game ends when all of the cars have crossed the finish line. Payouts are given to players according to their race results:

* '''winner of the race''': 12M$
* '''second''': 9M$
* '''third''': 6M$
* '''fourth''': 4M$
* '''fifth''': 2M$

Additionally, betting payouts are awarded as follows:

* '''first bet''':
** betting on the winner: 9M$
** betting on the second: 6M$
** betting on the third: 3M$
* '''second bet''':
** betting on the winner: 6M$
** betting on the second: 4M$
** betting on the third: 2M$
* '''third bet''':
** betting on the winner: 3M$
** betting on the second: 2M$
** betting on the third: 1M$

== Variants ==

Powers can be added into the game for additional complexity and more dynamic games. During each car auction, a power is attached to a car an the winner of the auction get the power. If a player has several powers, they must choose only one.

The base powers are the following:

* '''Aggressive''': If you play a card with your car at the top the the card, you may move that car 1 additional space
* '''Cunning''': You always move your cars, even on other player's turns
* '''Determined''': On any player's turn, if your car moved into only rectangular spaces, you may move it 2 additional spaces
* '''Strategic''': If you play a speed car with all six colors on it, you may ignore one color of it
* '''Tricky''': On your turn, you may move the cars in reverse order, from lower to highest
* '''Unpredictable''': If you play a card with a wild on it, you may use that wild for a color that is already on the card

If the "additional powers" option is selected, the powers from the ''Danger Circuit'' expansion are added into the game:

* '''Ambitious''': On any player's turn, if your car crosses a betting line you may move it additional spaces
* '''Experienced''': On any player's turn, if any car starts its movement in a space directly ahead of your car, you may move your car into the space that car moved out of
* '''Tough''': On any player's turn, if your car ends its movement in a space adjacent to a rumble strip, you may move it 2 additional spaces
* '''Bold''': On your turn, if your car would move 1 or 2 spaces, move it 3 spaces instead
* '''Defensive''': If none of your cars move on your turn, move one of your cars 3 spaces
* '''Reckless''': On your turn, if your car moves through a Tight Space, you may move it 2 additional spaces

BGA Studio Cookbook

2020-05-12T21:01:16Z

Bdrieu: Add CSS tricks

{{Studio_Framework_Navigation}}

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

== Visual Effects, Layout and Animation ==

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

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

Note: this method is recommended by BGA guildlines

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

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

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

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

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

'''Ingredients:''' ggg.js

Note: Not recommended

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

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

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

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

in .css file:

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

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

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

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

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

=== Use thematic fonts ===

'''Ingredients:''' ggg.css

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

[[File:Dragonline_font.png]]

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

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

=== Use player color in template ===

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

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

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

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

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

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

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

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

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

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

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

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

=== Dynamic tooltips ===

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

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

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

The string function return becomes the innerHTML of the tooltip, so it can be anything (matchedNode in this case) dojo node representing dom object with id of "divItemId" but there are more parameters which I am not posting here which allows more sophisticated subnode queries.

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

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

=== Accessing images from js ===

'''Ingredients:''' ggg.js
ggg.js

<pre>
// your game resources

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

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

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

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

So you want nice pictures in the game log, what do you do? First idea that come to mind is to send html from php in notifications.
This is bad idea for many reasons
* Its bad architecture, ui elements leak into server now you have to manage ui in many places
* If you decided to change something in ui in future version, old games reply and tutorials may not work, since they use stored notifications
* When you read log preview for old games its unreadable (this is log before you enter the game reply, useful for troubleshooting or game analysis)
* Its more data to transfer and store in db
* Its nightmare for translators

So what else can you do? I use this recipe which I is client side log injection. I intercept log arguments and replace them by html on my client side.

[[File:clientloginjection.png|left]]

ggg.js

<pre>

/** Override this function to inject html for log items */

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

if (!this.isSpectator)
args.You = this.divYou(); // will replace ${You} with colored version

// list of other known variables
var keys = ['place_name','token_name'];

for ( var i in keys) {
var key = keys[i];
if (typeof args[key] == 'string') {
args[key] = this.getTokenDiv(key, args);
}
}
}
} catch (e) {
console.error(log,args,"Exception thrown", e.stack);
}
return this.inherited(arguments);
},

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

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

</pre>

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

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

default:
break;
}

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

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

ggg.game.php:

$this->notifyPlayer($player_id,'playerLog',clienttranslate('${You} moved cube'),['You'=>'You']);

ggg.game.php:

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

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

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

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

==== Alternative way ====

Here is an example of what was done for Terra Mystica which is maybe not as good, but is more simple and straightforward:

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

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

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

<pre>
function getLogsPowerAmount( $amount )
{
return "<div class='tmlogs_icon' title='Power'><div class='power_amount'>$amount</div></div>";
}
</pre>

=== High-Definition Graphics ===

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

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

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

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

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

For instance:

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

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

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

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

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

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

== Game Model and Database design ==

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

[[File:Madeira board.png]]

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

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

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

Variant 1: Minimalistic

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

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

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

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

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

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

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

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

Variant 3: More normalised

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

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

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

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

=== Database for The card game ===

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

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

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

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

Variant 1: Minimalistic

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

Variant 2: More normalised

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

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

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

== Game Modules ==

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

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

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

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

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

require_once ('modules/ggg_other.php');

== Assorted Stuff ==

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

'''Ingredients:''' ggg.js

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

So lets do Select Worker/Place Worker

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

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

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

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

=== Multi Step Interactions: Action Stack - Using Client States ===

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

* We have euro game where game actions consist of series of mini-actions, which can be triggered by multiple sources
* Example: Russian RailRoads have multiple source of actions, such as worker slots, triggered advantages, triggered factory rewards, etc. Each of the consist of series of small action, such as "advance black rail + advance marker", once you start executing it, more mini-actions are triggered and added to the stack (in case of RRR its not a stack but a random access list but whatever)
* Implementing such game with server states is rather difficult because
** it require lots of states
** require stack on the state machine to support return to the state we originated substate from
** series can result in invalid game state (i.e. not allowed by rules), which it hard to roll back over multiple states
** without undo it would be rather frustrating for the player, and undo is hard to implement

So this is how to implemented it using action stack and client states

Encode all mini-actions as identifier or a letter, I use letters personally

For each action, trigger, etc, define a "rules" of that game element using mini-action encoding and store in material.inc.php so both server and client have access to it, no need to store it in database, rules are not going to change
during the game.

'''material.inc.php:'''

$this->token_types = array(
...
'slot_action_14' => array(
'name' => clienttranslate("Industry Advancement"),
'rules'=>"i",
),
'slot_action_15' => array(
'name' => clienttranslate("2 Industry Advancements"),
'rules'=>"ii",
),
'slot_action_16' => array(
'name' => clienttranslate("Industry and Black Track Advancement"),
'rules'=>"ib",
),
);

In game.php you send this to client
'''ggg.game.php:'''
protected function getAllDatas() {
...
// this is material fields
$result ['token_types'] = $this->token_types;
...
}

In .js when client selects original action, you read this field and push actions into stack, something like

this.pushOperations(this.gamedatas.token_types[action_id].rules);
this.processAction();

And processAction() will allow user to deal with possible actions. If this is truly a stack you could have done something like
processAction: function() {
var op = this.popOperation();
switch (op) {
case 'i':
this.setClientState("client_playerTurnSelectAdvantageToken", {
descriptionmyturn : "${you} must select industry marker to move",
});
break;
...
}
}
In Russian Railroads its unordered list, so it has to offer user all possible choices driven by current unprocessed operations, then determine what operation was that from the list based on what they clicked, i.e.

onMoveable : function(event) {
...
else if (id.startsWith('ind')) {
if (!this.commitOperation('i', id, place_id)) return;
}
this.gamedatas_local.tokens[id] = place_id; // alter local model
this.placeToken(id, place_id); // client side animation
if (this.checkAchievementMoveable(new_state, old_state, id)) { // that will check if something is triggered, so we can push more stuff on the stack
this.processAction();
}
}
During client states data is collected and pushed into client array of performed operations, we also do client side animation and alter model, since we don't send intermediate steps to server.

In example above we check if we client on industry marker, we will "commit" "i" operation with selected id of the marker and place_id. The commit is just pushing this data into an array.

All this operations later are send to server, usually when user clicks Done.
The data will be encoded for server to read into a string, i.e. i__ind2__indslot15, means move industry marker number 2 into slot 15 of industry track. And multiple operations
can be separated by a space for example.

At anytime during client states user can click Cancel which will restore last server state and undo all client animation back to last stored state.

The only disadvantage of this method is you have to implement a lot of functionality two times - on server and client.

Players actions: yourgamename.action.php

2020-05-10T17:20:04Z

Bdrieu:

{{Studio_Framework_Navigation}}

== Purpose of this file ==

With this file, you define all the player entry points (i.e., possible game actions) for your game.

This file is a sort of "bridge" between the AJAX calls you perform from the Javascript client side, and your main PHP code in "yourgame.game.php".

The role of the methods defined in this file is to filter the arguments, format them a bit, and then call a corresponding PHP method from your main game logic ("yourgame.game.php" file).

Methods in this file should be short: no game logic must be introduced here.

== Example of typical action method ==

(from Reversi example)

<pre>
public function playDisc()
{
self::setAjaxMode();
$x = self::getArg( "x", AT_posint, true );
$y = self::getArg( "y", AT_posint, true );
$result = $this->game->playDisc( $x, $y );
self::ajaxResponse( );
}
</pre>

== Methods to use in action methods ==

'''function setAjaxMode()'''

Must be used at the beginning of each action method.

'''function ajaxResponse()'''

Must be used at the end of each action method.

'''function getArg( $argName, $argType, $mandatory=false, $default=NULL, $argTypeDetails=array(), $bCanFail=false )'''

This method must be used to retrieve the arguments sent with your AJAX query.

You must ''not'' use "_GET", "_POST" or equivalent PHP variables to do this, as it is unsafe.

This method uses the following arguments:

* argName: the name of the argument to retrieve.
* argType: the type of the argument. You should use one of the following:
'AT_int' for an integer
'AT_posint' for a positive integer
'AT_float' for a float
'AT_bool' for 1/0/true/false
'AT_enum' for an enumeration (argTypeDetails lists the possible values as an array)
'AT_alphanum' for a string with 0-9a-zA-Z_ and space
'AT_numberlist' for a list of numbers separated with "," or ";" (example: 1,4;2,3;-1,2).
'AT_base64' for a base64-encoded string.
* mandatory: specify "true" if the argument is mandatory.
* default: if mandatory=false, you can specify here a default value in case the argument is not present.
* argTypeDetails: see AT_enum above.
* bCanFail: if true, specify that it may be possible that the argument won't be of the type specified by argType (and then do not log this as a fatal error in the system, and return a standard exception to the player).

'''function isArg( $argName )'''

This is a useful method when you only want to check if an argument is present or not present in your AJAX request (and don't care about the value).

It returns "true" or "false" according to whether "argName" has been specified as an argument of the AJAX request or not.

== Useful tip: retrieve a list of numbers ==

If your Javascript sends a list of integers separated by ";" (example: "1;2;3;4") as an argument, you can transform them into a PHP array with the following:

<pre>
public function playCards()
{
self::setAjaxMode();

$card_ids_raw = self::getArg( "card_ids", AT_numberlist, true );

// Removing last ';' if exists
if( substr( $card_ids_raw, -1 ) == ';' )
$card_ids_raw = substr( $card_ids_raw, 0, -1 );
if( $card_ids_raw == '' )
$card_ids = array();
else
$card_ids = explode( ';', $card_ids_raw );

$this->game->playCards( $card_ids );
self::ajaxResponse( );
}
</pre>