Board Game Arena - User contributions [en]

Gamehelpriftforce

2024-12-17T17:45:49Z

Elliot K:

== Overview ==
Riftforce is a 2 player game. You face up head to head, turn after turn.

If a player reaches 12 points the end of the game is triggered. Finally the player with the most points wins (of course).

The game starts with the guild selection and with players taking turns.

== Guild Selection ==
The base game contains 10 guilds. Each guild has a unique ability you can activate on your turn.
One guild is assigned randomly to every player. From the remaining 8 guilds, one is discarded. From the remaining 7 cards the players draft guilds until every player has 4 guilds.

For each guild, 4 elementals with 5 life points, 3 elementals with 6 life points, and 2 elementals with 7 life points are shuffled and 7 cards are drawn to start the game.

== Turn Overview ==
On your turn you perform 1 action. You can choose from these 3 possible actions:

*• Play Cards
*• Activate
*• Check & Draw

After that your opponent takes a turn, also choosing one action and then it comes back to you.

== Possible Actions ==

=== Play ===
Play up to 3 elementals from your hand to locations on your side of the Rift. They must either all show the same symbol or all show the same number.

You can play these elementals either

*• individually to three adjacent locations (1 elemental per location)
*• together in an order of your choice all to the same location

'''Note that the outermost locations on both ends are not considered adjacent to each other.'''

=== Activate ===
Select 1 elemental from your hand, show it face up and discard it your discard pile.

Activate up to 3 elementals that either

*• all show the same number
*• all show the same symbol

as the just discarded elemental.

The elementals you activate can be at any location and do not have to be adjacent to each other.

When you activate an elemental, it uses the ability described on its guild’s summoner. You must resolve all steps of the ability in order from top to bottom as much as you can.

When elementals change their position through abilities they are placed at the last position of the new location.

With most abilities you will place damage on the „first enemy”. This is the elemental closest to the location.

When you activate an elemental, resolve its ability completely and then check if you destroyed any elementals before activating your next elemental.

If the damage total on an elemental is equal to or higher than its number, that elemental is destroyed (discarded to the players discard pile). You gain 1 Riftforce for each destroyed enemy.

If an ability places more damage on an elemental than is needed to destroy it, the excess damage is not carried over to the next elemental.

=== Check & Draw ===
You can only choose this action if you have less than 7 elementals in your hand.

Check if you control any of the locations. You control a location if at least 1 of your elementals and no enemy is present there.

You gain 1 Riftforce for each controlled location.

If you choose this action only you can gain Riftforce even if your opponent controls locations at that moment.

Now draw elementals from your draw pile until you have 7 elementals in your hand.

== GAME END ==
As soon as a player reaches 12 Riftforce the game end is triggered.

After finishing the action completely, the opponent gets a last action if the player triggering the game end is the starting player. That way both of you get the same amount of actions.

Deck

2022-02-22T18:04:22Z

Elliot K: Mention possible consequences of overflowing DB field size limits with location names including player IDs

{{Studio_Framework_Navigation}}

"Deck" is one of the most useful component on the PHP side. With "Deck", you can manage the cards in your game on the server side.

Using "deck", you will be able to use the following features without writing a single SQL database request:
* Place cards in a pile, shuffle cards, draw cards one by one or many at a time.
* "Auto-reshuffle" the discard pile into the deck when the deck is empty.
* Move cards between different locations: hands of players, the table, etc.

== Using Deck: Hearts example ==

The Deck component is extensively used in the sample ''Hearts'' card game. You will find in "hearts.game.php" that the object "$this->cards" is used many times.

== Deck overview ==

With Deck component, you manage all cards of your game.

=== The 5 properties of each card ===

Using the Deck component, each card will have 5 properties:
* '''id''': This is the unique ID of each card.
* '''type''' and '''type_arg''': These two values define the type of your card (i.e., what sort of card is this?).
* '''location''' and '''location_arg''': These two values define where the card is at now.

The id, type, and type_arg properties are constants throughout the game. location and location_arg change when your cards move from one place to another in the game area.

'''id''' is the unique ID of each card. Two cards cannot have the same ID. IDs are generated automatically by the Deck component when you create cards during the Setup phase of your game.

'''type''' and '''type_arg''' defines the type of your card.

'''type''' is a short string, and '''type_arg''' is an integer.

You can use these two values as you like to make sure you will be able to identify the different cards in the game. See usage of "type" and "type_arg" below.

Examples of usage of "type" and "type_arg":
* In ''Hearts'', "type" represents the color (suite) of the card (1 to 4) and "type_arg" is the value of the card (1, 2, ... 10, J, Q, K).
* In ''Seasons'', "type" represents the type of the card (e.g., 1 is Amulet of Air, 2 is Amulet of Fire, etc...). type_arg is not used.
* In ''Takenoko'', a Deck component is used for objective cards. "type" is the kind of objective (irrigation/panda/plot) and "type_arg" is the ID of the specific objective to realize (e.g., "green bamboo x4"). Note that a second Deck component is used in ''Takenoko'' to manage the "garden plot" pile.

'''location''' and '''location_arg''' define where a card is at now. '''location''' is a short string, and '''location_arg''' is an integer.

You can use 'location' and 'location_arg' as you like, to move your card within the game area.

There are 3 special 'location' values that Deck manages automatically. You can choose to use these locations or not, depending on your needs:
* 'deck': the 'deck' location is a standard draw deck. Cards are placed face down in a stack and are drawn in sequential order during the game. 'location_arg' is used to specify where the card is located within the stack (the card with the highest location_arg value is the next to be drawn).
* 'hand': the 'hand' location represents cards in a player's hand. 'location_arg' is set to the ID of each player.
* 'discard': the 'discard' location is used for discard piles. Card in 'discard' may be reshuffled into the deck if needed (see "autoreshuffle").

Tips: using the Deck component, you will use generic properties ("location", "type_arg",...) for specific purposes in your game. Thus, during the design step before realizing your game, take a few minutes to write down the exact meaning of each of these generic properties in the context of your game.

=== Create a new Deck component ===

For each Deck component in your game, you need to create a dedicated table in the SQL database. This table has a standard format. In practice, if you just want to have a Deck component named "card", you can copy/paste the following into your "dbmodel.sql" file:

<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: the database schema of this table does not have to be exactly what is listed above. You can increase the size of the fields or add more fields. For additional fields
you just have to do manual queries.

In particular, if you are going to have deck locations specific to individual players, you may wish to use their player IDs in the card_location field. Those IDs can be 8+ characters long, leaving only 8 characters for the rest of the name if you use the varchar(16). If you exceed the size of the field, it will get silently truncated, which can be very difficult to troubleshoot!

Once you have done this (and restarted your game), you can declare the Deck component in your PHP code in your class constructor. For ''Hearts'' for example, I added to the "Hearts()" method:

<pre>
$this->cards = self::getNew( "module.common.deck" );
$this->cards->init( "card" );
</pre>

Note that we specify "card" here: the name of our previously created table. This means you can create several "Deck" components with multiple tables:

<pre>
$this->firstKindCards = self::getNew( "module.common.deck" );
$this->firstKindCards ->init( "first_kind_card" );
$this->secondKindCards = self::getNew( "module.common.deck" );
$this->secondKindCards ->init( "second_kind_card" );
</pre>

Most of the time this is not useful; a Deck component should manage all objects of the same kind (i.e., all cards in the game).
Note that you need to create a table for each "Deck", table name should be "first_kind_card" but the fields must remain "card_id", "card_type" and so on.

Afterwards, we can initialize your "Deck" by creating all the cards of the game. Generally, this is done only once during the game, in the "setupNewGame" method.

The "Deck" component provides a fast way to initialize all your cards at once: createCards. Here is how it is used for "Hearts":
<pre>
// Create cards
$cards = array();
foreach( $this->colors as $color_id => $color ) // spade, heart, diamond, club
{
for( $value=2; $value<=14; $value++ ) // 2, 3, 4, ... K, A
{
$cards[] = array( 'type' => $color_id, 'type_arg' => $value, 'nbr' => 1);
}
}

$this->cards->createCards( $cards, 'deck' );
</pre>

As you can see, "createCards" takes a description of all cards of the game. For each type of card, you have to specify its "type", "type_arg" and the number of cards to create ("nbr"). "createCards" create all cards and place them into the "deck" location (as specified in the second argument).

Now, you are ready to use "Deck"!

=== Simple examples using Deck ===

(Most examples are from "Hearts" game)

<pre>
// In "getAllDatas', we need to send to the current player all the cards he has in hand:
$result['hand'] = $this->cards->getCardsInLocation( 'hand', $player_id );
</pre>

<pre>
// At some time we want to check if all the cards (52) are in player's hands:
if( $this->cards->countCardInLocation( 'hand' ) == 52 )
// do something
</pre>

<pre>
// When a player plays a card in front of him on the table:
$this->cards->moveCard( $card_id, 'cardsontable', $player_id );

// Note the use of the custom location 'cardsontable' here to keep track of cards on the table.
</pre>

<pre>
// This is a new hand: let's gather all cards from everywhere in the deck:
$this->cards->moveAllCardsInLocation( null, "deck" );

// And then shuffle the deck
$this->cards->shuffle( 'deck' );

// And then deal 13 cards to each player
// Deal 13 cards to each players
// Create deck, shuffle it and give 13 initial cards
$players = self::loadPlayersBasicInfos();
foreach( $players as $player_id => $player )
{
$cards = $this->cards->pickCards( 13, 'deck', $player_id );

// Notify player about his cards
self::notifyPlayer( $player_id, 'newHand', '', array(
'cards' => $cards
) );
}

// Note the use of "notifyPlayer" instead of "notifyAllPlayers": new cards is a private information ;)
</pre>

== Deck component reference ==

=== Initializing Deck component ===

'''init( $table_name )'''

Initialize the Deck component.

Argument:
* table_name: name of the DB table used by this Deck component.

Must be called before any other Deck method.

Usually, init is called in your game constructor.

Example with Hearts:

<pre>
function Hearts( )
{
(...)

$this->cards = self::getNew( "module.common.deck" );
$this->cards->init( "card" );
}
</pre>

'''createCards( $cards, $location='deck', $location_arg=null )'''

Create card items in your deck component. Usually, all card items are created once, during the setup phase of the game.

"cards" describe all cards that need to be created. "cards" is an array with the following format:

<pre>
// Create 1 card of type "1" with type_arg=99,
// and 4 cards of type "2" with type_arg=12,
// and 2 cards of type "3" with type_arg=33

$cards = array(
array( 'type' => 1, 'type_arg' => 99, 'nbr' => 1 ),
array( 'type' => 2, 'type_arg' => 12, 'nbr' => 4 ),
array( 'type' => 3, 'type_arg' => 33, 'nbr' => 2 )
...
);
</pre>

Note: During the "createCards" process, Deck generates unique IDs for all card items.

Note: createCards is optimized to create a lot of cards at once. Do not use it to create cards one by one.

If "location" and "location_arg" arguments are not set, newly created cards are placed in the "deck" location. If "location" (and optionally location_arg) is specified, cards are created for this specific location.

=== Card standard format ===

When Deck component methods are returning one or several cards, the following format is used:

<pre>
array(
'id' => .., // the card ID
'type' => .., // the card type
'type_arg' => .., // the card type argument
'location' => .., // the card location
'location_arg' => .. // the card location argument
);
</pre>

=== Picking cards ===

'''pickCard( $location, $player_id )'''

Pick a card from a "pile" location (ex: "deck") and place it in the "hand" of specified player.

Return the card picked or "null" if there are no more card in given location.

This method supports auto-reshuffle (see "auto-reshuffle" below).

'''pickCards( $nbr, $location, $player_id )'''

Pick "$nbr" cards from a "pile" location (ex: "deck") and place them in the "hand" of specified player.

Return an array with the cards picked (indexed by the card ID), or "null" if there are no more card in given location.

Note that the number of cards picked can be less than "$nbr" in case there are not enough cards in the pile location.

This method supports auto-reshuffle (see "auto-reshuffle" below). In case there are not enough cards in the pile, all remaining cards are picked first, then the auto-reshuffle is triggered, then the other cards are picked.

'''pickCardForLocation( $from_location, $to_location, $location_arg=0 )'''

This method is similar to 'pickCard', except that you can pick a card for any sort of location and not only the "hand" location.

* from_location is the "pile" style location from where you are picking a card.
* to_location is the location where you will place the card picked.
* if "location_arg" is specified, the card picked will be set with this "location_arg".

This method supports auto-reshuffle (see "auto-reshuffle" below).

'''pickCardsForLocation( $nbr, $from_location, $to_location, $location_arg=0, $no_deck_reform=false )'''

This method is similar to 'pickCards', except that you can pick cards for any sort of location and not only the "hand" location.

* from_location is the "pile" style location from where you are picking some cards.
* to_location is the location where you will place the cards picked.
* if "location_arg" is specified, the cards picked will be set with this "location_arg".
* if "no_deck_reform" is set to "true", the auto-reshuffle feature is disabled during this method call.

This method supports auto-reshuffle (see "auto-reshuffle" below).

=== Moving cards ===

'''moveCard( $card_id, $location, $location_arg=0 )'''

Move the specific card to given location.

* card_id: ID of the card to move.
* location: location where to move the card.
* location_arg: if specified, location_arg where to move the card. If not specified "location_arg" will be set to 0.

'''moveCards( $cards, $location, $location_arg=0 )'''

Move the specific cards to given location.

* cards: an array of IDs of cards to move.
* location: location where to move the cards.
* location_arg: if specified, location_arg where to move the cards. If not specified "location_arg" will be set to 0.

'''insertCard( $card_id, $location, $location_arg )'''

Move a card to a specific "pile" location where card are ordered.

If location_arg place is already taken, increment all cards after location_arg in order to insert new card at this precise location.

(note: insertCardOnExtremePosition method below is more useful in most of the case)

'''insertCardOnExtremePosition( $card_id, $location, $bOnTop )'''

Move a card on top or at bottom of given "pile" type location. (Lower numbers: bottom of the deck. Higher numbers: top of the deck.)

(note: Filling an empty location this way with N cards creates "location_arg"s from 1 to N if "$bOnTop" is true and -1 to -N if "$bOnTop" is false. This can cause off-by-one errors for code intended to run on a deck generated by "shuffle( $location )" which generates "location_arg"s from 0 to N - 1.)

'''moveAllCardsInLocation( $from_location, $to_location, $from_location_arg=null, $to_location_arg=0 )'''

Move all cards in specified "from" location to given location.

* from_location: where to take the cards. If null, cards from all locations will be move.
* to_location: where to put the cards
* from_location_arg (optional): if specified, only cards with given "location_arg" are moved.
* to_location_arg (optional): if specified, cards moved "location_arg" is set to given value. Otherwise "location_arg" is set to 0.

Note: if you want to keep "location_arg" untouched, you should use "moveAllCardsInLocationKeepOrder" below.

'''moveAllCardsInLocationKeepOrder( $from_location, $to_location )'''

Move all cards in specified "from" location to given "to" location. This method does not modify the "location_arg" of cards.

'''playCard( $card_id )'''

Move specified card at the top of the "discard" location.

Note: this is an alias for: insertCardOnExtremePosition( $card_id, "discard", true )

=== Get cards informations ===

'''getCard( $card_id )'''

Get specific card information.

Return null if this card is not found.

'''getCards( $cards_array )'''

Get specific cards information.

$cards_array is an array of card IDs.

If some cards are not found or if some card IDs are specified multiple times, the method throws an (unexpected) Exception.

'''getCardsInLocation( $location, $location_arg = null, $order_by = null )'''

Get all cards in specific location, as an array. Return an empty array if the location is empty.

* location (string): the location where to get the cards.
* location_arg (optional): if specified, return only cards with the specified "location_arg".
* order_by (optional): if specified, returned cards are ordered by the given database field. Example: "card_id" or "card_type".

'''countCardInLocation( $location, $location_arg=null )'''

Return the number of cards in specified location.

* location (string): the location where to count the cards.
* location_arg (optional): if specified, count only cards with the specified "location_arg".

'''countCardsInLocations()'''

Return the number of cards in each location of the game.

The method returns an associative array with the format "location" => "number of cards".

Example:
<pre>
array(
'deck' => 12,
'hand' => 21,
'discard' => 54,
'ontable' => 3
);
</pre>

'''countCardsByLocationArgs( $location )'''

Return the number of cards in each "location_arg" for the given location.

The method returns an associative array with the format "location_arg" => "number of cards".

Example: count the number of cards in each player's hand:
<pre>
countCardsByLocationArgs( 'hand' );

// Result:
array(
122345 => 5, // player 122345 has 5 cards in hand
123456 => 4 // and player 123456 has 4 cards in hand
);
</pre>

'''getPlayerHand( $player_id )'''

Get all cards in given player hand.

Note: This is an alias for:
getCardsInLocation( "hand", $player_id )

'''getCardOnTop( $location )'''

Get the card on top of the given ("pile" style) location, or null if the location is empty.

Note that the card pile won't be "auto-reshuffled" if there is no more card available.

'''getCardsOnTop( $nbr, $location )'''

Get the "$nbr" cards on top of the given ("pile" style) location.

The method return an array with at most "$nbr" elements (or a void array if there is no card in this location).

Note that the card pile won't be "auto-reshuffled" if there is not enough cards available.

'''getExtremePosition( $bGetMax ,$location )'''

(rarely used)

Get the position of cards at the top of the given location / at the bottom of the given location.

Of course this method works only on location in "pile" where you are using "location_arg" to specify the position of each card (example: "deck" location).

If bGetMax=true, return the location of the top card of the pile.

If bGetMax=false, return the location of the bottom card of the pile.

'''getCardsOfType( $type, $type_arg=null )'''

Get all cards of a specific type (rarely used).

Return an array of cards, or an empty array if there is no cards of the specified type.

* type: the type of cards
* type_arg: if specified, return only cards with the specified "type_arg".

'''getCardsOfTypeInLocation( $type, $type_arg=null, $location, $location_arg = null )

Get all cards of a specific type in a specific location (rarely used).

Return an array of cards, or an empty array if there is no cards of the specified type.

* type: the type of cards
* type_arg: if specified, return only cards with the specified "type_arg".
* location (string): the location where to get the cards.
* location_arg (optional): if specified, return only cards with the specified "location_arg".

=== Shuffling ===

'''shuffle( $location )'''

Shuffle all cards in specific location.

Shuffle only works on locations where cards are on a "pile" (ex: "deck").

Please note that all "location_arg" will be reset to reflect the new order of the cards in the pile.

=== Auto-reshuffle ===

To enable auto-reshuffle you must do "$this->cards->autoreshuffle = true" during the setup of the component (often in the ''_construct'' function when you ''init()'' the Deck object).

Every time a card must be retrieved from the "deck" location, if it is empty the "discard" location will be automatically reshuffled into the "deck" location.

If you need to notify players when the deck is shuffled, you can setup a callback method using this feature: $this->cards->autoreshuffle_trigger = array('obj' => $this, 'method' => 'deckAutoReshuffle');

If you need to use other locations than "deck" and "discard" for auto-reshuffle feature, you can configure it this way: $this->cards->autoreshuffle_custom = array('deck' => 'discard'); (replace 'deck' and 'discard' with your custom locations).

Gamehelpuptown

2021-12-31T20:09:48Z

Elliot K: /* Objective */

== Objective ==
The goal of Uptown is to place your colored tiles in such a way that at the end of the game, they're connected in as few groups of as possible. A group is a collection of tiles which are all touching at least one other member of the group on at least one side (not just on a corner). Note: The NUMBER of groups is important, not the SIZE of the groups.

If two or more players have the same number of groups at the end of the game, the player who has captured the fewest of their opponents' tiles wins. See below for more about capturing.

== Playing the Game ==
Below the board you can see the five tiles that are in your rack and available to place. On your turn, click one of these tiles, then click the space on the board where you want to place it. To be a legal move, the tile you're playing must match the board space where you're trying to place it. You can only place tiles with a letter on them (A-I) in the row with a matching label. You can only place tiles with a number (1-9) in the matching column. You can only place tiles with a symbol (man, ring, woman, street sign, skyline, saxophone, automobile, playing cards, champagne) in the area of the board with matching symbols on it. The dollar sign ($) tile is wild and you can place it anywhere.

Your supply includes one tile of each letter, number, and symbol as well as a single dollar sign ($) tile. The game ends when each player has DRAWN (not played) all of their tiles and each player has taken a final turn (each player will have four un-played tiles). You can see how many tiles are left for you and your opponents to draw by looking at the number in the user information area in the top right corner of the page.

=== Capturing ===
If you wish to place a tile on a square where an opponent has already placed one of their tiles, you may do so. However, you may not split an opponent's tiles into more groups than they already had. You may also never capture one of your own tiles.

You can see any tiles that your opponents have captured displayed below their names. Tiles that you have captured appear below your rack of tiles - a captured tile cannot be played. At the end of the game, if two or more players have the same number of groups, the player with fewest captured tiles wins.

== Game End ==
After all players draw their final tiles, everyone gets one final turn and then the game ends. At the end of the game, you will have four un-played tiles left.

== BGA Scoring ==
BGA counts each distinct set of 1 or more tiles as 1 NEGATIVE point, the closer your score is to 0 (and the fewer captures you've made) the better you are doing! If 2 or more players have the same score, the player with the fewest captures wins. If 2 or more players have the same score AND the same number of captures, enjoy the win together - or enjoy a playoff game!

== Variants ==
=== Blockers ===
Blockers! changed the end of game scoring rules. Instead of the number of captured tiles being a tie breaker, the largest number of captures tiles of a single color gets added to a player's score. So if a player were to end the game with one group and three captured blue tiles, they would lose to a player with two groups and only a single capture in each color.

Stock

2021-04-30T23:27:04Z

Elliot K: Document bug with Safari off-center sprites and work-around

{{Studio_Framework_Navigation}}

== Overview ==

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

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

Examples of stock use cases:

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

Using stock:

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

== Using stock: a simple example ==

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

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

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

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

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

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

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

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

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

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

Explanation:

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

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

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

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

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

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

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

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

== Complete stock component reference ==

=== Creation ===

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

With create, you create a new stock component.

Parameters:
* page: the container page. Usually: "this".
* container_div: the container "div" element (an empty div element in your template, with an id).
* width and height (in pixels) for the stock component.

(See ''Hearts'' example above).

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

Define a new type of item and add it to the stock.

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

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

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

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

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

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

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

=== Add/Remove items ===

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

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

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

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

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

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

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

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

This is especially useful:

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

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

Remove an item of the specific type from the stock.

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

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

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

Remove an item with a specific ID from the stock.

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

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

'''removeAll()'''

Remove all items from the stock.

'''removeAllTo( to )'''

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

=== Getters ===

'''getPresentTypeList()'''

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

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

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

'''count():'''

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

'''getAllItems()'''

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

'''getItemDivId(id)'''

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

'''getItemById(id)'''

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

=== Selection ===

'''setSelectionMode( mode )'''

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

'''setSelectionAppearance( type )'''

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

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

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

'''isSelected( id )'''

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

'''selectItem( id )'''

Select the specified item.

'''unselectItem( id )'''

Unselect the specified item.

'''unselectAll()'''

Unselect all items of the stock.

'''onChangeSelection'''

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

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

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

(...)

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

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

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

'''getSelectedItems()'''

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

'''getUnselectedItems()'''

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

=== Layout ===

'''resetItemsPosition()'''

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

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

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

'''item_margin'''

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

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

'''changeItemsWeight( newWeights )'''

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

Items are immediately re-sorted with the new weight.

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

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

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

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

'''centerItems'''

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

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

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

By default, horizontal_overlap and vertical_overlap are 0.

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

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

See the games "Jaipur" or "Koryŏ" to see examples of use of this function.

'''autowidth'''

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

=== Customize apperance ===

'''extraClasses'''

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

this.playerHand.extraClasses='mycard';

Note that it is the same list for all items.

'''onItemCreate'''

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

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

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

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

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

</pre>

'''onItemDelete'''

Function handler called when div is removed

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

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

Most cases will be one of the following situations:

'''Situation A''':

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

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

'''Situation B''':

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

* On the destination Stock, use '''addToStockWithId''' with a "from" argument which is the HTML id of the corresponding item in the source Stock. For example, if the source stock id is "myHand", then the HTML id of card 48 is "myHand_item_48".
* Then, remove the source item with '''removeFromStockById'''.

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

'''Situation C''':

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

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

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

You can customize this (showing the default value):
<pre>

this.mystock.jstpl_stock_item= "<div id=\"${id}\" class=\"stockitem\" style=\"top:${top}px;left:${left}px;width:${width}px;height:${height}px;z-index:${position};background-image:url('${image}');\"></div>";
</pre>
To produce a different type of stock item

== Known issues ==

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

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

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

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

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

Main game logic: Game.php

2021-04-10T21:37:22Z

Elliot K: Clarify that notifyPlayer() cannot notify spectators

{{Studio_Framework_Navigation}}

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

== File Structure ==

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

Here is the basic structure:

* Constructor: where you define global variables.
* setupNewGame: initial setup of the game. Takes an array of players, indexed by player_id. Structure of each player includes player_name, player_canal, player_avatar, and flags indicating admin/ai/premium/order/language/beginner.
* getAllDatas: where you retrieve all game data during a complete reload of the game. Returned value must include ['players'][playerId]['score'] for scores to populate when F5 is pressed.
* getGameProgression: where you compute the game progression indicator. Returns a number indicating percent of progression (0-100)
* Utility functions: your utility functions.
* Player actions: the entry points for players actions.
* Game state arguments: methods to return additional data on specific game states ([http://en.doc.boardgamearena.com/Your_game_state_machine:_states.inc.php#args more info here]).
* Game state actions: the logic to run when entering a new game state ([http://en.doc.boardgamearena.com/Your_game_state_machine:_states.inc.php#action more info here]).
* zombieTurn: what to do it's the turn of a zombie player.
* upgradeTableDb: function to migrate database if you change it after release on production.

== Accessing player information ==

'''Important''': In the following methods, be mindful of the difference between the "active" player and the "current" player. The '''active''' player is the player whose turn it is - not necessarily the player who sent a request! The '''current''' player is the player who sent the request and will see the results returned by your methods: not necessarily the player whose turn it is!

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

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

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

; loadPlayersBasicInfos()
: Get an associative array with generic data about players (ie: not game specific data).
: The key of the associative array is the player id. The returned table is cached, so ok to call multiple times without performance concerns.
: The content of each value is:
: * player_name - the name of the player
: * player_color (ex: ff0000) - the color code of the player
: * player_no - the position of the player at the start of the game in natural table order, i.e. 1,2,3

; getCurrentPlayerId()
: Get the "current_player". The current player is the one from which the action originated (the one who sent the request).
: '''Be careful''': This is not necessarily the active player!
: In general, you shouldn't use this method, unless you are in "multiplayer" state.
: '''Very important''': in your setupNewGame and zombieTurn function, you must never use getCurrentPlayerId() or getCurrentPlayerName(), otherwise it will fail with a "Not logged" error message (these actions are triggered from the main site and propagated to the gameserver from a server, not from a browser. As a consequence, there is no current player associated to these actions).

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

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

; isCurrentPlayerZombie()
: Check the "current_player" zombie status. If true, player is zombie, i.e. left or was kicked out of the game.

; isSpectator()
: Check the "current_player" spectator status. If true, the user accessing the game is a spectator (not part of the game). For this user, the interface should display all public information, and no private information (like a friend sitting at the same table as players and just spectating the game).

; getActivePlayerColor()
: This function does not seems to exist in API, if you need it here is implementation
function getActivePlayerColor() {
$player_id = self::getActivePlayerId();
$players = self::loadPlayersBasicInfos();
if( isset( $players[ $player_id ]) )
return $players[ $player_id ]['player_color'];
else
return null;
}

== Accessing the database ==

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

'''IMPORTANT'''

BGA uses [http://dev.mysql.com/doc/refman/5.0/en/sql-syntax-transactions.html database transactions]. This means that your database changes WON'T BE APPLIED to the database until your request ends normally (web request, not database request). Using transactions is in fact very useful for you; at any time, if your game logic detects that something is wrong (example: a disallowed move), you just have to throw an exception and all changes to the game situation will be removed. This also means that you need not (and in fact cannot) use your own transactions for multiple related database operations.

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

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

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

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

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

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

</pre>

; getNonEmptyCollectionFromDB( $sql )
: Same as getCollectionFromDB($sdl), but raise an exception if the collection is empty. Note: this function does NOT have 2nd argument as previous one does.

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

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

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

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

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

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

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

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

</pre>

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

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

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

; escapeStringForDB( $string )
: You must use this function on every string type data in your database that contains unsafe data.
: (unsafe = can be modified by a player).
: This method makes sure that no SQL injection will be done through the string used.
: Note: if you using standard types in ajax actions, like AT_alphanum it is sanitized before arrival,
: this is only needed if you manage to get unchecked string, like in the games where user has to enter text as a response.

<pre>

</pre>

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

== Use globals ==

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

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

'''initGameStateLabels'''

This method should be located at the beginning of ''yourgamename.php.'' This is where you define the globals used in your game logic, by assigning them IDs.

You can define up to 80 globals, with IDs from 10 to 89 (inclusive). You must '''not''' use globals outside this range, as those values are used by other components of the framework.

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

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

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

'''getGameStateValue( $value_label )'''

Retrieve the current value of a global.

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

Set the current value of a global.

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

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

Return the final value of the global.

== Game states and active players ==

=== Activate player handling ===

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

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

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

; $this->getActivePlayerId()
: Return the "active_player" id
: Note: it does NOT mean that this player is active right now, because state type could be "game" or "multipleactiveplayer"
: Note: avoid using this method in a "multipleactiveplayer" state because it does not mean anything.

=== Multiple activate player handling ===

; $this->gamestate->setAllPlayersMultiactive()
: All playing players are made active. Update notification is sent to all players (this will trigger '''onUpdateActionButtons''').
: Usually, you use this method at the beginning of a game state (e.g., "stGameState") which transitions to a ''multipleactiveplayer'' state in which multiple players have to perform some action. Do not use this method if you going to make some more changes in the active player list. (I.e., if you want to take away multipleactiveplayer status immediately afterwards, use setPlayersMultiactive instead.)

Example of usage:
<pre>
function st_MultiPlayerInit() {
$this->gamestate->setAllPlayersMultiactive();
}
</pre>

And this is the state declaration:
<pre>
2 => array(
"name" => "playerTurnPlace",
"description" => clienttranslate('Other player must place ships'),
"descriptionmyturn" => clienttranslate('${you} must place ships (click on YOUR SHIPS board to place)'),
"type" => "multipleactiveplayer",
'action' => 'multiPlayerDoSomething',
'args' => 'arg_playerTurnPlace',
"possibleactions" => array( "actionBla" ),
"transitions" => array( "next" => 4, "last" => 99)
),
</pre>

; $this->gamestate->setAllPlayersNonMultiactive( $next_state )
: All playing players are made inactive. Transition to next state

; $this->gamestate->setPlayersMultiactive( $players, $next_state, $bExclusive = false )
: Make a specific list of players active during a multiactive gamestate. Update notification is sent to all players whose state changed.
: "players" is the array of player id that should be made active.
: If "exclusive" parameter is not set or false it doesn't deactivate other previously active players. If its set to true, the players who will be multiactive at the end are only these in "$players" array

: In case "players" is empty, the method trigger the "next_state" transition to go to the next game state.
: returns true if state transition happened, false otherwise

; $this->gamestate->setPlayerNonMultiactive( $player_id, $next_state )
: During a multiactive game state, make the specified player inactive.
: Usually, you call this method during a multiactive game state after a player did his action. It is also possible to call it directly from multiplayer action handler.
: If this player was the last active player, the method trigger the "next_state" transition to go to the next game state.
: returns true if state transition happened, false otherwise
Example of usage (see state declaration of playerTurnPlace above):
<pre>
function actionBla($args) {
self::checkAction('actionBla');
// handle the action using $this->getCurrentPlayerId()
$this->gamestate->setPlayerNonMultiactive( $this->getCurrentPlayerId(), 'next');
}
</pre>

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

; $this->gamestate->updateMultiactiveOrNextState( $next_state_if_none )
: Sends update notification about multiplayer changes. All multiactive set* functions above do that, however if you want to change state manually using db queries for complex calculations, you have to call this yourself after. Do not call this if you calling one of the other setters above.
Example: you have player teams and you want to activate all players in one team
<pre>
$sql = "UPDATE player SET player_is_multiactive='0'";
self::DbQuery( $sql );
$sql = "UPDATE player SET player_is_multiactive='1' WHERE player_id='$player_id' AND player_team='$team_no'";
self::DbQuery( $sql );

$this->gamestate->updateMultiactiveOrNextState( 'error' );
</pre>

; updating database manually
: Use this helper function to change multiactive state without sending notification
<pre>
/**
* Changes values of multiactivity in db, does not sent notifications.
* To send notifications after use updateMultiactiveOrNextState
* @param number $player_id, player id <=0 or null - means ALL
* @param number $value - 1 multiactive, 0 non multiactive
*/
function dbSetPlayerMultiactive($player_id = -1, $value = 1) {
if (! $value)
$value = 0;
else
$value = 1;
$sql = "UPDATE player SET player_is_multiactive = '$value' WHERE player_zombie = 0 and player_eliminated = 0";
if ($player_id > 0) {
$sql .= " AND player_id = $player_id";
}
self::DbQuery($sql);
}
</pre>

=== States functions ===
; $this->gamestate->nextState( $transition )
: Change current state to a new state. Important: the $transition parameter is the name of the transition, and NOT the name of the target game state, see [[Your game state machine: states.inc.php]] for more information about states.

; $this->checkAction( $actionName, $bThrowException=true )
: Check if the current player can perform a specific action in the current game state, and optionally throw an exception if they can't.
: The action is valid if it is listed in the "possibleactions" array for the current game state (see game state description).
: This method MUST be the first one called in ALL your PHP methods that handle player actions, in order to make sure a player doesn't perform an action not allowed by the rules at the point in the game. It should not be called from methods where the current player is not necessarily the active player, otherwise it may fail with an "It is not your turn" exception.
: If "bThrowException" is set to "false", the function returns '''false''' in case of failure instead of throwing an exception. This is useful when several actions are possible, in order to test each of them without throwing exceptions.

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

This is how PHP action looks that returns player to active state (only for multiplayeractive states). To be able to execute on js side do not checkAction on js side for this specific one.

function actionUnpass() {
$this->gamestate->checkPossibleAction('actionUnpass'); // player chane mind about passing while others were thinking
$this->gamestate->setPlayersMultiactive(array ($this->getCurrentPlayerId() ), 'error', false);
}

; $this->gamestate->state()
: Get an associative array of current game state attributes, see [[Your game state machine: states.inc.php]] for state attributes.
$state=$this->gamestate->state(); if( $state['name'] == 'myGameState' ) {...}

== Players turn order ==

'''getNextPlayerTable()'''

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

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

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

'''getPrevPlayerTable()'''

Same as above, but the associative array associate the previous player around the table. However there no 0 index here.

'''getPlayerAfter( $player_id )'''

Get player playing after given player in natural playing order.

'''getPlayerBefore( $player_id )'''

Get player playing before given player in natural playing order.

Note: There is no API to modify this order, if you have custom player order you have to maintain it in your database
and have custom function to access it.

'''createNextPlayerTable( $players, $bLoop=true )'''

Using $players array creates a map of current => next as in example from getNextPlayerTable(), however you can use custom order here.
Parmeter $bLoop is true if last player points to first, false otherwise.
In any case index 0 points to first player (first element of $players array). $players is array of player ids in desired order.

N.B: This function '''DOES NOT''' allow to change players turn order!

Example of usage:
<pre>
function getNextPlayerTableCustom() {
$starting = $this->getStartingPlayer(); // custom function to get starting player
$player_ids = $this->getPlayerIdsInOrder($starting); // custom function to create players array starting from starting player
return self::createNextPlayerTable($player_ids, false); // create next player table in custom order
}
</pre>

== Notify players ==

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

'''IMPORTANT'''

Notifications are sent at the very end of the request, when it ends normally. It means that if you throw an exception for any reason (ex: move not allowed), no notifications will be sent to players.
Notifications sent between the game start (setupNewGame) and the end of the "action" method of the first active state will never reach their destination.

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

Send a notification to all players of the game.

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

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

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

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

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

You can use arguments in your notification_log strings, that refers to values defines in the "notification_args" argument (see below).
Note: Make sure you only use single quotes ('), otherwise PHP will try to interpolate the variable and will ignore the values in the args array.

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

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

Complete notifyAllPlayers example (from "Reversi"):

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

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

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

'''Important''': this array is serialized to be sent to the browsers, and will be saved with the notification to be able to replay the game later. If it is too big, it can make notifications slower / less reliable, and replay archives very big (to the point of failing). So as a general rule, you should send only the minimum of information necessary to update the client interface with no overhead in order to keep the notifications as light as possible.

'''Important''': When the game page is reloaded (i.e. F5 or when loading turn based game) all previous notifications are replayed as history notifications. These notifications do not trigger notification handlers and are used basically to build the game log. Because of that most of the notification arguments, expect i18n, player_id and all arguments used in the message, are removed from these history notifications. If you need additional arguments in history notifications you can add special field preserveArgsInHistory to notification arguments, like this:

<pre>
self::notifyAllPlayers( "playDisc", clienttranslate( '${player_name} plays a disc and turns over ${returned_nbr} disc(s)' ),
array(
'player_id' => $player_id,
'player_name' => self::getActivePlayerName(),
'returned_nbr' => count( $turnedOverDiscs ),
'x' => $x,
'y' => $y,
'preserveArgsInHistory' => [ 'x', 'y' ]
) );
</pre>
In this example, fields x and y will be preserved when replaying history notification at the game load.

Note: you CAN use some HTML inside your notification log, however it not recommended 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, at least don't put HTML tags inside the "clienttranslate" method. You can use a notification argument instead, and provide your HTML through this argument.

If you still want to have pretty pictures in the log check this [[BGA_Studio_Cookbook#Inject_images_and_styled_html_in_the_log]].

If your notification contains some phrases that build programmatically you may need to use recursive notifications. In this case the argument can be not only the string but
an array itself, which contains 'log' and 'args', i.e.

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

Special handling of arguments:
* ${player_name} - this will be wrapped in html and text shown using color of the corresponding player, some colors also have reserved background. This will apply recursively as well.
* ${player_name2} - same

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

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

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

Important: the variable for player name must be ${player_name} in order to be highlighted with the player color in the game log. If you want a second player name in the log, name the variable ${player_name2}, etc.

Note that spectators cannot be notified using this method, because their player ID is not available via loadPlayersBasicInfos() or otherwise. You must use notifyAllPlayers() for any notification that spectators should get.

== About random and randomness ==

A large number of board games rely on random, most often based on dice, cards shuffling, picking some item in a bag, and so on. This is very important to ensure a high level of randomness for each of these situations.

Here's are a list of techniques you should use in these situations, from the best to the worst.

=== Dice and bga_rand ===

'''bga_rand( min, max )'''
This is a BGA framework function that provides you a random number between "min" and "max" (inclusive), using the best available random method available on the system.

This is the preferred function you should use, because we are updating it when a better method is introduced.

As of now, bga_rand is based on the PHP function "random_int", which ensures a cryptographic level of randomness.

In particular, it is '''mandatory''' to use it for all '''dice throw''' (ie: games using other methods for dice throwing will be rejected by BGA during review).

Note: rand() and mt_rand() are deprecated on BGA and should not be used anymore, as their randomness is not as good as "bga_rand".

=== shuffle and cards shuffling ===

To shuffle items, like a pile of cards, the best way is to use the BGA PHP [[Deck]] component and to use "shuffle" method. This ensures that the best available shuffling method is used, and that if in the future we improve it your game will be up to date.

As of now, the Deck component shuffle method is based on PHP "shuffle" method, which has quite good randomness (even it is not as good as bga_rand). In consequence, we accept other shuffling methods during reviews, as long as they are based on PHP "shuffle" function (or similar, like "array_rand").

=== Other methods ===

Mysql "RAND()" function has not enough randomness to be a valid method to get a random element on BGA. This function has been used in some existing games and has given acceptable results, but now it should be avoided and you should use other methods instead.

== Game statistics ==

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

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

'''initStat( $table_or_player, $name, $value, $player_id = null )'''

Create a statistic entry with a default value.

This method must be called for each statistic of your game, in your setupNewGame method.
If you neglect to call this for a statistic, and also do not update the value during the course of a certain game using setStat or incStat, the value of the stat will be undefined rather than 0. This will result in it being ignored at the end of the game, as if it didn't apply to that particular game, and excluded from cumulative statistics. As a consequence - if do not want statistic to be applied, do not init it, or call set or inc on it.

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

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

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

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

Set a statistic $name to $value.

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

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

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

Increment (or decrement) specified statistic value by $delta value. Same behavior as setStat function.

'''getStat( $name, $player_id = null )'''

Return the value of statistic specified by $name. Useful when creating derivative statistics such as average.

== Translations ==

See [[Translations]]

== Manage player scores and Tie breaker ==

=== Normal scoring ===

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

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

Examples:
<pre>

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

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

</pre>

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

=== Tie breaker ===

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

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

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

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

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

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

=== Co-operative game ===

To make everyone win/lose together in a full-coop game:

Add the following in gameinfos.inc.php :
'is_coop' => 1, // full cooperative

Assign a score of zero to everyone if it's a loss.
Assign the same score > 0 to everyone if it's a win.

=== Semi-coop ===

If the game is not full-coop, then everyone loses = everyone is tied. I.e. set score to 0 to everybody.

=== Only "winners" and "losers" ===

For some games, there is only a group (or a single) "winner", and everyone else is a "loser", with no "end of game rank" (1st, 2nd, 3rd...).

Examples:
* Coup
* Not Alone
* Werewolves
* Quantum

In this case:
* Set the scores so that the winner has the best score, and the other players have the same (lower) score.
* Add the following lines to gameinfos.inc.php:

<pre>
// If in the game, all losers are equal (no score to rank them or explicit in the rules that losers are not ranked between them), set this to true
// The game end result will display "Winner" for the 1st player and "Loser" for all other players
'losers_not_ranked' => true,
</pre>

Werewolves and Coup are implemented like this, as you can see here:
* https://boardgamearena.com/#!gamepanel?game=werewolves&section=lastresults
* https://boardgamearena.com/#!gamepanel?game=coupcitystate&section=lastresults

Adding this has the following effects:
* On game results for this game, "Winner" or "Loser" is going to appear instead of the usual "1st, 2nd, 3rd, ...".
* When a game is over, the result of the game will be "End of game: Victory" or "End of game: Defeat" depending on the result of the CURRENT player (instead of the usual "Victory of XXX").
* When calculating ELO points, if there is at least one "Loser", no "victorious" player can lose ELO points, and no "losing" player can win ELO point. Usually it may happened because being tie with many players with a low rank is considered as a tie and may cost you points. If losers_not_ranked is set, we prevent this behavior and make sure you only gain/loss ELO when you get the corresponding results.

Important: this SHOULD NOT be used for cooperative games (see is_coop parameter), or for 2 players games (it makes no sense in this case).

=== Solo ===

If game supports solo variant, a negative or zero score means defeat, a positive score means victory.

=== Player elimination ===

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

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

Usage:

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

=== Scoring Helper functions ===

These functions should have been API but they are not, just add them to your php game and use for every game.

// get score
function dbGetScore($player_id) {
return $this->getUniqueValueFromDB("SELECT player_score FROM player WHERE player_id='$player_id'");
}

// set score
function dbSetScore($player_id, $count) {
$this->DbQuery("UPDATE player SET player_score='$count' WHERE player_id='$player_id'");
}

// set aux score (tie breaker)
function dbSetAuxScore($player_id, $score) {
$this->DbQuery("UPDATE player SET player_score_aux=$score WHERE player_id='$player_id'");
}

// increment score (can be negative too)
function dbIncScore($player_id, $inc) {
$count = $this->dbGetScore($player_id);
if ($inc != 0) {
$count += $inc;
$this->dbSetScore($player_id, $count);
}
return $count;
}

== Reflexion time ==

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

== Undo moves ==

Please read our [[BGA Undo policy]] before.

'''Important''': Before using these methods, you must also add the following to your "gameinfos.inc.php" file, otherwise these methods are ineffective:
'db_undo_support' => true

; function undoSavepoint( )
: Save the whole game situation inside an "Undo save point".
: There is only ONE undo save point available (see [[BGA Undo policy]]). Cannot use in multiactivate state or in game state where next state is multiactive.
: Note: this function does not actually do anything when it is called, it only raises the flag to store the database AFTER transaction is over. So the actual state will be saved when you exit the function calling it (technically before first queued notification is sent, which matter if you transition to game state not to user state after), which may affect what you end up saved.

; function undoRestorePoint()
: Restore the situation previously saved as an "Undo save point".
: You must make sure that the active player is the same after and before the undoRestorePoint (ie: this is your responsibility to ensure that the player that is active when this method is called is exactly the same than the player that was active when the undoSavePoint method has been called).

function actionUndo() {
self::checkAction('actionUndo');
$this->undoRestorePoint();
$this->gamestate->nextState('next'); // transition to single player state (i.e. beginning of player actions for this turn)
}

== Managing errors and exceptions ==

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

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

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

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

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

== Zombie mode ==

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

While developing your zombie mode, keep in mind that:
* Do not refer to the rules, because this situation is not planned by the rules.
* Try to figure that you are playing with your friends and one of them has to leave: how can we finish the game without killing the spirit of the game?
* The idea is NOT to develop an artificial intelligence for the game.
* Do not try to end the game early, even in a two-player game. The zombie is there to allow the game to continue, not to end it. Trying to end the game is not supported by the framework and will likely cause unexpected errors.

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

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

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

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

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

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

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

'''Very important''': your zombie code will be called when the player leaves the game. This action is triggered from the main site and propagated to the gameserver from a server, not from a browser. As a consequence, there is no current player associated to this action. In your zombieTurn function, you must '''never''' use getCurrentPlayerId() or getCurrentPlayerName(), otherwise it will fail with a "Not logged" error message.

== Player color preferences ==

BGA players (Club members) may now choose their preferred color for playing. For example, if they are used to play green for every board game, they can select "green" in their BGA preferences page.

Making your game compatible with colors preferences is very easy and requires only 1 line of PHP and 1 configuration change :

On your gameinfos.inc.php file, add the following lines :

// Favorite colors support : if set to "true", support attribution of favorite colors based on player's preferences (see reattributeColorsBasedOnPreferences PHP method)
// NB: this parameter is used only to flag games supporting this feature; you must use (or not use) reattributeColorsBasedOnPreferences PHP method to actually enable or disable the feature.
'favorite_colors_support' => true,

Then, on your main <your_game>.game.php file, find the "reloadPlayersBasicInfos" call in your "setupNewGame" method and replace :

$sql .= implode( $values, ',' );
self::DbQuery( $sql );
self::reloadPlayersBasicInfos();

By :

$sql .= implode( $values, ',' );
self::DbQuery( $sql );
self::reattributeColorsBasedOnPreferences( $players, array( /* LIST HERE THE AVAILABLE COLORS OF YOUR GAME INSTEAD OF THESE ONES */"ff0000", "008000", "0000ff", "ffa500", "773300" ) );
self::reloadPlayersBasicInfos();

The "reattributeColorsBasedOnPreferences" method reattributes all colors, taking into account players color preferences and available colors.

Note that you must update the colors to indicate the colors available for your game.

2 important remarks :
* for some games (ex : Chess), the color has an influence on a mechanism of the game, most of the time by giving a special advantage to a player (ex : Starting the game). Color preference mechanism must NOT be used in such a case.
* your logic should NEVER consider that the first player has the color X, that the second player has the color Y, and so on. If this is the case, your game will NOT be compatible with reattributeColorsBasedOnPreferences as this method attribute colors to players based on their preferences and not based as their order at the table.

Colours currently listed as a choice in preferences:

* #ff0000 Red
* #008000 Green
* #0000ff Blue
* #ffa500 Yellow
* #000000 Black
* #ffffff White
* #e94190 Pink
* #982fff Purple
* #72c3b1 Cyan
* #f07f16 Orange
* #bdd002 Khaki green
* #7b7b7b Gray

== Legacy games API ==

For some very specific games ("legacy", "campaign"), you need to keep some informations from a game to another.

This should be an exceptional situation: the legacy API is costing resources on Board Game Arena databases, and is slowing down the game setup process + game end of game process. Please do not use it for things like:
* keeping a player preference/settings (=> player preferences and game options should be used instead)
* keeping a statistics, a score, or a ranking, while it is not planned in the physical board game, or while there is no added value compared to BGA statistics / rankings.

You should use it for:
* legacy games: when some components of the game has been altered in a previous game and should be kept as it is.
* "campaign style" games: when a player is getting a "reward" at the end of a game, and should be able to use it in further games.

Important: you cannot store more than 64k of data (serialized as JSON) per player per game. If you go over 64k, storeLegacyData function is going to FAIL, and there is a risk to create a major bug (= players blocked) in your game. You MUST make sure that no more than 64k of data is used for each player for your game. For example, if you are implementing a "campaign style" game and if you allow a player to start multiple campaign, you must LIMIT the number of different campaign so that the total data size to not go over the limit. We strongly recommend you to use this:

try
{
$this->storeLegacyTeamData( 'my_variable', $my_data );
}
catch( feException $e )
{
if( $e->getCode() == FEX_legacy_size_exceeded )
{
// Do something here to free some space in Legacy data (ex: by removing some variables)
}
else
throw $e;
}

The keys may only contain letters and numbers, underscore seems not to be allowed.

; function storeLegacyData( $player_id, $key, $data, $ttl = 365 )
: Store some data associated with $key for the given user / current game
: In the opposite of all other game data, this data will PERSIST after the end of this table, and can be re-used
: in a future table with the same game.
: IMPORTANT: The only possible place where you can use this method is when the game is over at your table (last game action). Otherwise, there is a risk of conflicts between ongoing games.
: TTL is a time-to-live: the maximum, and default, is 365 days.
: In any way, the total data (= all keys) you can store for a given user+game is 64k (note: data is store serialized as JSON data)

; function retrieveLegacyData( $player_id, $key )
: Get data associated with $key for the current game
: This data is common to ALL tables from the same game for this player, and persist from one table to another.
: Note: calling this function has an important cost => please call it few times (possibly: only ONCE) for each player for 1 game if possible
: Note: you can use '%' in $key to retrieve all keys matching the given patterns

; function removeLegacyData( $player_id, $key )
: Remove some legacy data with the given key
: (useful to free some data to avoid going over 64k)

; function storeLegacyTeamData( $key, $data, $ttl = 365 )
: Same as storeLegacyData, except that it stores some data for the whole team within the current table
: Ie: if players A, B and C are at a table, the legacy data will be saved for future table with (exactly) A, B and C on the table.
: This is useful for games which are intended to be played several time by the same team.
: Note: the data total size is still limited, so you must implement catch the FEX_legacy_size_exceeded exception if it happens

; function retrieveLegacyTeamData($key)
: Same as retrieveLegacyData, except that it retrieves some data for the whole team within the current table (set by storeLegacyTeamData)

; function removeLegacyTeamData()
: Same as removeLegacyData, except that it retrieves some data for the whole team within the current table (set by storeLegacyTeamData)

== Language dependent games API ==

This API is used for games that are heavily language dependent. Two most common use cases are:
* Games that have a language dependent component that are not necessarily translatable, typically a list of words. (Think of games like Codenames, Decrypto, Just One...)
* Games with massive communication where players would like to ensure that all participants speak the same language. (Think of games like Werewolf, The Resistance, maybe even dixit...)

If this option is used, the table created will be limited only to users that have specific language in their profile. Player starting the game would be able to chose one of the languages he speaks.

There is a new property language_dependency in gameinfos.inc.php which can be set like this:
'language_dependecy' => false, //or if the property is missing, the game is not language dependent
'language_dependecy' => true, //all players at the table must speak the same language
'language_dependecy' => array( 1 => 'en', 2 => 'fr', 3 => 'it' ), //1-based list of supported languages

In the gamename.game.php file, you can get the id of selected language with the method '''getGameLanguage'''.
; function getGameLanguage()
: Returns an index of the selected language as defined in gameinfos.inc.php.

Languages currently available on BGA are:
'ar' => array( 'name' => "العربية", 'code' => 'ar_AE' ), // Arabic
'be' => array( 'name' => "беларуская мова", 'code' => 'be_BY' ), // Belarusian
'bn' => array( 'name' => "বাংলা", 'code' => 'bn_BD' ), // Bengali
'bg' => array( 'name' => "български език", 'code' => 'bg_BG' ), // Bulgarian
'ca' => array( 'name' => "català", 'code' => 'ca_ES' ), // Catalan
'cs' => array( 'name' => "čeština", 'code' => 'cs_CZ' ), // Czech
'da' => array( 'name' => "dansk", 'code' => 'da_DK' ), // Danish
'de' => array( 'name' => "deutsch", 'code' => 'de_DE' ), // German
'el' => array( 'name' => "Ελληνικά", 'code' => 'el_GR' ), // Greek
'en' => array( 'name' => "English", 'code' => 'en_US' ), // English
'es' => array( 'name' => "español", 'code' => 'es_ES' ), // Spanish
'et' => array( 'name' => "eesti keel", 'code' => 'et_EE' ), // Estonian
'fi' => array( 'name' => "suomi", 'code' => 'fi_FI' ), // Finnish
'fr' => array( 'name' => "français", 'code' => 'fr_FR' ), // French
'he' => array( 'name' => "עברית", 'code' => 'he_IL' ), // Hebrew
'hi' => array( 'name' => "हिन्दी", 'code' => 'hi_IN' ), // Hindi
'hr' => array( 'name' => "Hrvatski", 'code' => 'hr_HR' ), // Croatian
'hu' => array( 'name' => "magyar", 'code' => 'hu_HU' ), // Hungarian
'id' => array( 'name' => "Bahasa Indonesia", 'code' => 'id_ID' ), // Indonesian
'ms' => array( 'name' => "Bahasa Malaysia", 'code' => 'ms_MY' ), // Malaysian
'it' => array( 'name' => "italiano", 'code' => 'it_IT' ), // Italian
'ja' => array( 'name' => "日本語", 'code' => 'ja_JP' ), // Japanese
'jv' => array( 'name' => "Basa Jawa", 'code' => 'jv_JV' ), // Javanese
'ko' => array( 'name' => "한국어", 'code' => 'ko_KR' ), // Korean
'lt' => array( 'name' => "lietuvių", 'code' => 'lt_LT' ), // Lithuanian
'lv' => array( 'name' => "latviešu", 'code' => 'lv_LV' ), // Latvian
'nl' => array( 'name' => "nederlands", 'code' => 'nl_NL' ), // Dutch
'no' => array( 'name' => "norsk", 'code' => 'nb_NO' ), // Norwegian
'oc' => array( 'name' => "occitan", 'code' => 'oc_FR' ), // Occitan
'pl' => array( 'name' => "polski", 'code' => 'pl_PL' ), // Polish
'pt' => array( 'name' => "português", 'code' => 'pt_PT' ), // Portuguese
'ro' => array( 'name' => "română", 'code' => 'ro_RO' ), // Romanian
'ru' => array( 'name' => "Русский язык", 'code' => 'ru_RU' ), // Russian
'sk' => array( 'name' => "slovenčina", 'code' => 'sk_SK' ), // Slovak
'sl' => array( 'name' => "slovenščina", 'code' => 'sl_SI' ), // Slovenian
'sr' => array( 'name' => "Српски", 'code' => 'sr_RS' ), // Serbian
'sv' => array( 'name' => "svenska", 'code' => 'sv_SE' ), // Swedish
'tr' => array( 'name' => "Türkçe", 'code' => 'tr_TR' ), // Turkish
'uk' => array( 'name' => "Українська мова", 'code' => 'uk_UA' ), // Ukrainian
'zh' => array( 'name' => "中文 (漢)", 'code' => 'zh_TW' ), // Traditional Chinese (Hong Kong, Macau, Taiwan)
'zh-cn' => array( 'name' => "中文 (汉)", 'code' => 'zh_CN' ), // Simplified Chinese (Mainland China, Singapore)

== Debugging and Tracing ==

To debug php code you can use some tracing functions available from the parent class such as debug, trace, error, warn, dump.

self::debug("Ahh!");
self::dump('my_var',$my_var);

See [[Practical_debugging]] section for complete information about debugging interfaces and where to find logs.

BGA Studio Cookbook

2021-04-09T20:36:36Z

Elliot K: Rename preserveArgsInHistory to preserve and explain about avoiding 0 and 1 array indexes

{{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_1
* 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

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

ggg.css:

<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 (IMPORTANT: from some '''free font''' source. See notes below).

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

'''NB:''' if you need to include a font that's not available online, an extra action will be needed from an admin. Please include the font file(s) in your img directory, and mention it to admins when requesting your game to be moved to alpha. '''Please remember that the font has to be free, and include a .txt with all appropriate license information about the font.'''
You can look for free fonts (for example) on https://fonts.google.com or https://www.fontsquirrel.com/)

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

Note: this method does not seems to work to retina resolution displays, if you know better way let me know

=== 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. In this example matchedNode is a 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 (i.e. you can attach tooltip to all nodes with class or whatever).

[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

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

=== Rendering text with players color and proper background ===

'''Ingredients:''' ggg.js

This example actually writes "You" but you can replace this with player name as easily, drop translating function in this case

<pre>
/* 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>

=== Inject icon images in the log ===

Here is an example of what was done for Terra Mystica which is 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>
Note: injecting html from php is not ideal but easy, if you want more clean solution, use method below but it is a lot more sophisticated.

=== 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? The first idea that comes to mind is to send html from php in notifications (see method above).

This is a bad idea for many reasons:

* It's bad architecture. ui elements leak into the server, and now you have to manage the ui in multiple places.
* If you decided to change something in the ui in future version, replay logs for old games and tutorials may not work, since they use stored notifications.
* Log previews for old games become unreadable. (This is the log state before you enter the game replay, which is useful for troubleshooting and game analysis.)
* It's more data to transfer and store in the db.
* It's a nightmare for translators.

So what else can you do? I use this recipe for '''client side log injection''' to intercept log arguments (which come from the server) and replace them with html on the client side.

[[File:clientloginjection.png|left]]

ggg.js

<pre>

/** Override this function to inject html into log items. This is a built-in BGA method. */

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

// list of special keys we want to replace with images
var keys = ['place_name','token_name'];

for ( var i in keys) {
var key = keys[i];
args[key] = this.getTokenDiv(key, args);

}
}
} catch (e) {
console.error(log,args,"Exception thrown", e.stack);
}
return this.inherited(arguments);
},
</pre>

'''Important:''' In the ''format_string_recursive'' method, the 'args' parameter will only contain arguments passed to it from the notify method in ggg.game.php (see below).

The 'log' parameter is the actual string that is inserted into the logs. You can perform additional js string manipulation on it.

<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 that in this case the server simply injects token_id as a name, and the client substitutes it for the translated name or the picture.

ggg.game.php:

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

'''Important:''' As noted above, only arguments actually passed by this method are available to the args parameter received in the client-side ''format_string_recursive'' method.

Sometimes it is the case that you want to pass arguments that are not actually included in the output message. For example, suppose we have a method like this:

$this->notifyAllPlayers('tokenPlaced',clienttranslate('Player placed ${token_name}'),array(
'token_name' => $token_id,
'zone_played' => $zone);

This will output "Player placed ${token_name}" in the log, and if we subscribe to a notification method activated by the "tokenPlaced" event in the client-side code, that method can make use of the 'zone_played' argument.

Now if you want to make some really cool things with game log, most probably you would need more arguments than are included in log message. The problem with that,
it will work at first, but if you reload game using F5 or when the game loads in turn based mode, 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 message are removed. In example above, field zone_played would be removed from historical log as it is not included in message of the notification. You can till preserve specific arguments in historical log by adding special field preserve to notification arguments like this:

<pre>
$this->notifyAllPlayers('tokenPlaced',clienttranslate('Player placed ${token_name}'),array(
'token_name' => $token_id,
'zone_played' => $zone,
'preserve' => [ 2 => 'zone_played' ]
);
</pre>

Now you can use zone_player in format_string_recursive even in historical logs. Note that for this to work, you currently need to define your own indexes for the 'preserve' array and avoid using 0 or 1.

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

==== Add option to disable shadows ====

Keep in mind that drop-shadow are very GPU intensive. This becomes noticeable once you have about 40 components with drop-shadow filter. If that is your case, you can quite easily implement a user preference to disable shadows for users on slower machines:

gameoptions.inc.php
<pre>
100 => array(
'name' => totranslate('Shadows'),
'needReload' => true, // after user changes this preference game interface would auto-reload
'values' => array(
1 => array( 'name' => totranslate( 'Enabled' ), 'cssPref' => '' ),
2 => array( 'name' => totranslate( 'Disabled' ), 'cssPref' => 'no-shadow' )
)
),
</pre>

[game].css
<pre>
.no-shadow * {
filter: none !important;
}
</pre>

==== Shadows with clip-path ====

For some reason, a shadow will not work together with clip-path on one element. To use both clip-path (when for example using .svg to cut out cardboard components from your .jpg spritesheet) and drop-shadow, you need to wrap the element into another one, and apply drop-shadow to the outer one, and clip-path to the inner one.

<pre>
<div class='my-token-wrap'>
<div class='my-token'>
</div>
</div>
</pre>
<pre>
.my-token-wrap {
filter: drop-shadow(0px 0px 1px #000000);
}
.my-token-wrap .my-token {
clip-path: url(#my-token-path);
}
</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 enough for that. The #overall-content 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: token_location, int: token_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
|}

See php module for this table here https://github.com/elaskavaia/bga-sharedcode/blob/master/modules/tokens.php

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

== Code Organization ==

=== 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 JavaScript module (II) ===

* Create ggg_other.js in modules/ folder and sync

define([], function () {
return "value";
});

* Modify ggg.js to include it

define([
"dojo",
"dojo/_base/declare",
"bgagame/modules/ggg_other",
"ebg/core/gamegui",
"ebg/counter"
], function(dojo, declare, other) {

});

This is maybe a little bit more the idea of the AMD Loader than the first option, although the first option should work as well.

A little explanation to this:
The define function loads all the modules listed in the array and calls the following function with these loaded modules as parameters.
By putting your module at the third position in the array it is passed as the third parameter to the function. Be aware that the modules are resolved by position only, not by name. So you can load the module '''ggg_other''' and pass it as a parameter with the name '''other'''. '''gamegui''' and '''counter''' are passed in as well, but when the parameters are not defined they are just skipped. Because these modules put their content into the global scope it does not matter and you can use them from there.

In the example above the string "value" is passed for the parameter '''other''', but the function in your module can return whatever you want. It can be an object, an array, something you declared with dojo.declare, you can return even functions.
Your module can load other modules. Just put them in the array at the beginning and pass them as parameters to your function.
The advantage of passing the values as parameter is that you do not need to put these values in the global scope, so they can't be collisions with values defined in other scripts or the BGA Framework.

The dojo toolkit provides good documentation to all of its components, the complete documentation for the AMD-Loader is here:
https://dojotoolkit.org/documentation/tutorials/1.10/modules/index.html It should be still correct, even as it seems to be only for version 1.10

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

=== Creating a test class to run PHP locally ===

'''Ingredients:''' ggg.game.php, stubs
For this you need stubs of other method you can use this for example
https://github.com/elaskavaia/bga-sharedcode/raw/master/misc/module/table/table.game.php

Create another php files, i.e ggg_test.php
<pre>
<?php
define("APP_GAMEMODULE_PATH", "misc/"); // include path to stubs, which defines "table.game.php" and other classes
require_once ('eminentdomaine.game.php');

class MyGameTest1 extends MyGame { // this is your game class defined in ggg.game.php
function __construct() {
parent::__construct();
include '../material.inc.php';// this is how this normally included, from constructor
}

// override/stub methods here that access db and stuff
function getGameStateValue($var) {
if ($var == 'round')
return 3;
return 0;
}
}
$x = new MyGameTest1(); // instantiate your class
$p = $x->getGameProgression(); // call one of the methods to test
if ($p != 50)
echo "Test1: FAILED";
else
echo "Test1: PASSED";

</pre>

Run from command line like
php7 ggg_test.php

If you do it this way - you can also use local php debugger (i.e. integrated with IDE or command line).

=== Avoiding code in dojo declare style ===
Dojo class declarations are rather bizzare and do not work with most IDEs.
If you want to write in plain JS with classes, you can stub all the dojo define/declare stuff
and hook your class into that, so the classes are outside of this mess.

NOTE: this technique is for experienced developers, do not try it if you do not understand
the consequences.

This is complete example of game .js class
<pre>
// Testla is game name is has to be changed
class Testla {
constructor(game) {
console.log('game constructor');
this.game = game;
this.varfoo = new MyFoo(); // this example of class from custom module
}

setup(gamedatas) {
console.log("Starting game setup", this.varfoo);
this.gamedatas = gamedatas;
this.dojo.create("div", { class: 'whiteblock', innerHTML: _("hello") }, 'thething');
console.log("Ending game setup");
};
onEnteringState(stateName, args) {
console.log('onEnteringState : ' + stateName, args);
this.game.addActionButton('b1',_('Click Me'), (e)=>this.onButtonClick(e));
};
onLeavingState(stateName) {
console.log('onLeavingState : ' + stateName, args);
};
onUpdateActionButtons(stateName, args) {
console.log('onUpdateActionButtons : ' + stateName, args);
};
onButtonClick(event) {
console.log('onButtonClick',event);
};
};

define([
"dojo", "dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
g_gamethemeurl + '/modules/foo.js' // custom module if needed
],
function(dojo, declare) {
// testla is game name is has to be changed
return declare("bgagame.testla", ebg.core.gamegui, {
constructor: function() {
this.xapp = new Testla(this);
this.xapp.dojo = dojo;
},
setup: function(gamedatas) {
this.xapp.setup(gamedatas);
},
onEnteringState: function(stateName, args) {
this.xapp.onEnteringState(stateName, args.args);
},
onLeavingState: function(stateName) {
this.xapp.onLeavingState(stateName, args);
},
onUpdateActionButtons: function(stateName, args) {
this.xapp.onUpdateActionButtons(stateName, args);
},
});
});

</pre>

=== More readable JS: onEnteringState ===

If you have a lot of states onEnteringState and friends become rather wild, you can do this trick to call some method dynamically.

<pre>

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

// Call appropriate method
var methodName = "onEnteringState_" + stateName;
if (this[methodName] !== undefined) {
console.log('Calling ' + methodName, args.args);
this[methodName](args.args);
}
},

onEnteringState_playerTurn: function(args) { // this is args directly, not args.args
// process
},

onEnteringState_playerSomethingElse: function(args) {
// process
},

</pre>

Note: since its ignores the undefined functions you don't have define function for each state, but on the other hand you cannot make typos.
Same applies to onUpdateActionButtons except you pass 'args' to method, not args.args, and for onLeavingState where you don't pass anything.

=== Frameworks and Preprocessors ===

* [[Using Vue]] - work-in-progress guide on using the modern framework Vue.js to create a game
* [[Using Typescript and Scss]] - How to auto-build Typescript and SCSS files to make your code cleaner

== Assorted Stuff ==

=== Out-of-turn actions: Un-pass ===

'''Ingredients:''' ggg.js, ggg.game.php, ggg.action.php, states.inc.php

In multiplayer game sometimes players passes but than they think more and want to un-Pass and redo their choice.
To re-active a player who passes some trickery required.

Define a special action that does how and hook it up.

In states.inc.php add an action to mmultipleactiveplayer state to "unpass", lets call it "actionCancel"

In ggg.action.php add action hook
public function actionCancel() {
self::setAjaxMode();
$this->game->actionCancel();
self::ajaxResponse();
}

In ggg.game.php add action handler
function actionCancel() {
$this->gamestate->checkPossibleAction('actionCancel');
$this->gamestate->setPlayersMultiactive(array ($this->getCurrentPlayerId() ), 'error', false);
}

Finally to call this in client ggg.js you would do something like:
<pre>
onUpdateActionButtons: function(stateName, args) {
if (this.isCurrentPlayerActive()) {
// ...
} else if (!this.isSpectator) { // player is NOT active but not spectatoe
switch (stateName) {
case 'playerTurnMuliPlayerState':
this.addActionButton('button_unpass', _('Oh no!'), 'onUnpass');
break;
}
}
}

onUnpass: function(e) {
this.ajaxcall("/" + this.game_name + "/" + this.game_name + "/actionCancel.html", {}, this); // no checkAction!
}
</pre>
Although be careful that if the turn comes back to the player while he is about to click cancel, the action buttons will be updated and the player will misclick which can be quite frustrating. To avoid this, move the cancel button to another position, like to the left of pagemaintitletext:
dojo.place('button_unpass', 'pagemaintitletext', 'before');
Being out of the generalactions div, it won't be automatically destroyed like normal buttons, so you'll have to handle that yourself in onLeavingState. You might also want to change the button color to red (blue buttons for active player only, red buttons also for inactive players?)

=== Multi Step Interactions: Select Worker/Place Worker - Using Selection ===

'''Ingredients:''' ggg.js

Simple way to implement something like that without extra states is to use "selection" mechanism. When user click on worker add some sort of class into that element i.e. 'selected' (which also have to have some indication by css i.e. outline).

Than user can click on placement zone, you can use dojo.query for "selected" element and use it along with zone id to send data to server. If proper worker is not selected yet can give a error message using this.showMessage(...) function.

Extra code required to properly cleanup selection between states

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

=== Assigning Player Order ===
Normally when game starts there is "natural" player order assigned randomly.

If you want to deliberatly assign player order at the start of the game (for example, in a game with teams options), you can do so by retrieving the initialization-only player attribute '''player_table_order''' and using it to assign values to '''player_no''' (which is normally assigned at the start of a game in the order in which players come to the table). (See [https://en.doc.boardgamearena.com/Game_database_model:_dbmodel.sql#The_player_table Game database model] for more details.)

'''Example:'''
<pre>
// Retrieve inital player order ([0=>playerId1, 1=>playerId2, ...])
$playerInitialOrder = [];
foreach ($players as $playerId => $player) {
$playerInitialOrder[$player['player_table_order']] = $playerId;
}
ksort($playerInitialOrder);
$playerInitialOrder = array_flip(array_values($playerInitialOrder));

// Player order based on 'playerTeams' option
$playerOrder = [0, 1, 2, 3];
switch (self::getGameStateValue('playerTeams')) {
case self::TEAM_1_2:
$playerOrder = [0, 2, 1, 3];
break;
case self::TEAM_1_4:
$playerOrder = [0, 1, 3, 2];
break;
case self::TEAM_RANDOM:
shuffle($playerOrder);
break;
default:
case self::TEAM_1_3:
// Default order
break;
}

// Create players
// Note: if you added some extra field on "player" table in the database (dbmodel.sql), you can initialize it there.
$sql =
'INSERT INTO player (player_id, player_color, player_canal, player_name, player_avatar, player_no) VALUES ';
$values = [];

foreach ($players as $playerId => $player) {
$color = array_shift($default_colors);
$values[] =
"('" .
$playerId .
"','$color','" .
$player['player_canal'] .
"','" .
addslashes($player['player_name']) .
"','" .
addslashes($player['player_avatar']) .
"','" .
$playerOrder[$playerInitialOrder[$playerId]] .
"')";
}
$sql .= implode(',', $values);
self::DbQuery($sql);
self::reattributeColorsBasedOnPreferences(
$players,
$gameinfos['player_colors']
);
self::reloadPlayersBasicInfos();
</pre>

=== Send different notifications to active player vs everybody else ===

'''Ingredients:''' ggg.js

Hack alert. This is a hack. We were hoping for proper solution by bga framework.

This will allow you to send notification with two message one for specific player and one for everybody else including spectators.
Note that this does not split the data - all data must be shared.

Add this to .js file (if you already overriding it merge obviously)
<pre>
/** @Override */
format_string_recursive: function(log, args) {
if (typeof args.log_others != 'undefined' && typeof args.player_id != 'undefined' && this.player_id != args.player_id)
log = args.log_others;
return this.inherited(arguments); // you must call this to call super
},
</pre>

Example of usage (from eminentdomain)
<pre>
$this->notifyAllPlayers('tokenMoved',
clienttranslate('${player_name} adds +2 Colonies to ${place_name}'), // notification with show for player with player_id
['player_id'=>$player_id, // this is mandatory
'log_others'=>clienttranslate('${player_name} adds +2 Colonies to an unknown planet'), // notification will show for others
...
]);
</pre>

=== Send transient notifications without incrementing move ID ===

'''Ingredients:''' ggg.php

Hack alert. This is a hack.

Use this if you need to send some transient notification that should not create a new move ID. The notification should be idempotent -- it should have no practical effect on the game state and would be '''safe to drop''' (e.g., it would not matter if a player never received this notification). For example, in a co-op game you want all players to see a real-time preview of some action, before the active player commits their turn.

Doing this mainly affects the instant replay & archive modes. During replay, the BGA framework automatically inserts a 1.5-second pause between each "move". With this hack, your transient notifications are not considered to be a "move", so no pause gets added.

; In ggg.php
<pre>
$this->not_a_move_notification = true; // note: do not increase the move counter
$this->notifyAllPlayers('cardsPreview', '', $args);
</pre>

BGA Code Sharing

2021-04-02T18:46:21Z

Elliot K: Add Uptown

{{Studio_Framework_Navigation}}

This page is for listing of externally hosted bga projects, tools and resources, as well as internal project
intended for sharing

== Projects hosted not in studio ==

See the table a link and nickname of the developer on bga (same as used for dev forum), and short description. See [[Tools_and_tips_of_BGA_Studio#Version_Control]] for some suggestions on how and where to publish your code externally. Also see the [https://github.com/topics/boardgamearena boardgamearena] tag on github.

'''Important notice about artwork on BGA Open Source projects: original hi-resolution images from publishers must not be published on the repositories. In addition, it is better to specify that the images derivated from publishers artwork are copyrighted and cannot be licensed under a free license like Creative Commons.
'''

{| class="wikitable"
|-
! NON-GAME PROJECTS
! CODE LINK
! DEVELOPER
|-
| Shared Code (not a game)
| https://github.com/elaskavaia/bga-sharedcode
| Victoria_La
|-
| BoardGameArena Workbench (not a game)
| https://github.com/danielholmes/bga-workbench
| Daniel Holmes (dhau)
|-
! GAME
! CODE LINK
! DEVELOPER
|-
| 99 (Trick-taking Card Game)
| https://github.com/ekelly/bga-ninetynine
| QuasarDukeDev
|-
| Assyria
| https://github.com/sebastien-prudhomme/bga-assyria
| daikinee
|-
| Bandido
| https://github.com/opheliehb/BandidoBGA
| ophelopede & Harkle
|-
| The Battle for Hill 218
| https://github.com/danielholmes/battle-for-hill-218
| Daniel Holmes (dhau)
|-
| Bonbons
| https://github.com/AntonioSoler/bga-bonbons
| Morgalad
|-
| Coinche
| https://github.com/drasill/bga-coinche
| Draasill
|-
| Coup: City State
| https://github.com/quietmint/bga-coupcitystate
| quietmint
|-
| Dungeon Roll
| https://github.com/MartinGoulet/bga-dungeonroll
| MGoulet
|-
| Egyptian Ratscrew
| https://github.com/0BuRner/bga-egyptianratscrew
| 0BuRner
|-
| Eruption
| https://github.com/AndyKerrison/bga-eruption
| Andy_K
|-
| A Fistful Of Gold
| https://bitbucket.org/Joel_L/fistfulofgold
| Brainchild
|-
| Florenza: The Card Game
| https://github.com/alberto-bottarini/bga-florenza
| tarini
|-
| Hearts '''(Tutorial)'''
| https://github.com/elaskavaia/bga-heartsla
| Victoria_La
|-
| Incan Gold
| https://github.com/AntonioSoler/bga-incangold
| Morgalad
|-
| Marco Polo
| https://github.com/rcitaliano/MarcoPolo
| rcitaliano
|-
| Nile
| https://github.com/AndyKerrison/bga-nile
| Andy_K
|-
| Noir: Killer vs Inspector
| https://bitbucket.org/chhuang76/bga_noirkvi
| ch huang
|-
| Penny Press
| https://github.com/AdamNovotny/bga-blooms
| A-dam
|-
| P.I.
| https://gitlab.com/fa81/bga-pi, https://github.com/hellp/bga-pi (mirror)
| Fabian Neumann (fa81)
|-
| Santorini
| https://github.com/AntonioSoler/bga-santorini
| Morgalad, quietmint, Tisaac
|-
| Tablut
| https://github.com/Lucas-C/tablut
| Lucas-C & ntaffore
|-
| Takara Island
| https://github.com/AntonioSoler/bga-takaraisland
| Morgalad
|-
| Taluva
| https://github.com/quietmint/bga-taluva
| Morgalad & quietmint
|-
| Teotihuacan: City of Gods
| https://github.com/Trompetenhut/bga-teotihuacan
| Trompetenhut
|-
| Uptown
| https://github.com/elliotkendall/bga-uptown
| SpottedShroom
|-
| Via Magica
| https://github.com/christopherburke/bga_viamagica
| CuriousTerran
|-
| Just Desserts
| https://github.com/mizutismask/bga-just-desserts
| mizutismask
|-
| The King's Guild
| https://github.com/AdamNovotny/BGG-KingsGuild
| A-dam
|-
| Get the MacGuffin
| https://github.com/mizutismask/bga-get-the-MacGuffin
| mizutismask
|-
| President
| https://github.com/quaresma95/president
| quaresma95
|-
| Hardback
| https://github.com/quietmint/bga-hardback
| quietmint
|-
| Dice Summoners
| https://github.com/eoincos/bga-dicesummoners
| eoincos
|-
|}

== Projects on studio ==

Any developer can add themselves to a project as read-only from http://en.studio.boardgamearena.com/#!projects page (almost any project).
The list below are no-games which do not have bgg id and not showing up there.

{| class="wikitable"
|-
! NAME
! CODE LINK
! DEVELOPER
|-
| Shared Code
| http://en.studio.boardgamearena.com/#!studiogame?game=sharedcode
| Victoria_La
|-
| Original BGA template
| http://en.studio.boardgamearena.com/#!studiogame?game=template
| Victoria_La
|-
|}

== Other useful resources ==

Moved to [[Tools_and_tips_of_BGA_Studio]]

Stock

2021-03-18T21:18:03Z

Elliot K: Explain that it's not possible to trigger on animation end actions with removeFromStock and removeFromStockById

Gamehelpuptown

2021-03-14T18:55:50Z

Elliot K: Explain the difference between Uptown and its re-release, Blockers!

== How to Play Uptown ==
=== Objective ===
The goal of Uptown is to place your colored tiles in such a way that at the end of the game, they're connected in as few groups as possible. A group is a collection of tiles which are all touching at least one other member of the group on at least one side (not just on a corner).

If one or more players has the same number of groups at the end of the game, the player who has captured the fewest of their opponents' tiles wins. See below for more about capturing.

=== Playing the Game ===
Below the board you can see the five tiles that are in your rack and available to place. On your turn, click one of these tiles, then click the space on the board where you want to place it. To be a legal move, the tile you're playing must match the board space where you're trying to place it. You can only place tiles with a letter on them (A-I) in the row with a matching label. You can only place tiles with a number (1-9) in the matching column. You can only place tiles with a symbol in the area of the board with matching symbols on it. The dollar sign ($) tile is wild and you can place it anywhere.

Your supply includes one tile of each letter, number, and symbol. The game ends when each player has drawn all of their tiles and placed all but four. Therefore, you there are four tiles you will not need to play. You can see how many tiles are left for you and your opponents to draw by looking at the number in the user information area in the top right corner of the page.

=== Capturing ===
If you wish to place a tile on a square where an opponent has already placed one of their tiles, you may do so. However, you may not split an opponent's tiles into more groups than they already had. You may also never capture one of your own tiles.

You can see any tiles that your opponents have captured displayed below their names. Tiles that you have captured appear below your rack of tiles. At the end of the game, if one or more players has the same number of groups, the player with fewest captured tiles wins.

=== Uptown vs. Blockers! ===
Uptown was originally published with a small print run in 2007. In 2011 it was rebranded and re-released as Blockers! In addition to a new abstract theme, Blockers! changed the end of game scoring rules. Instead of the number of captured tiles being a tie breaker, the largest number of captures tiles of a single color gets added to a player's score. So if a player were to end the game with one group and three captured blue tiles, they would lose to a player with two groups and only a single capture in each color.

Currently the version on BGA implements the original Uptown scoring. It may eventually support the option of using the Blockers! rules instead.

Gamehelpuptown

2021-03-10T22:32:15Z

Elliot K: Created page with "== How to Play Uptown == === Objective === The goal of Uptown is to place your colored tiles in such a way that at the end of the game, they're connected in as few groups as p..."