== Object of the game ==
NOT ALONE is an asymmetrical card game, with one player (the Creature) playing against the other players (the Hunted).

If you play as one of the Hunted, you explore Artemia using Place cards. By playing these and your Survival cards, your aim is to avoid being hunted down by the Creature until help arrives.

If you play as the Creature, your aim is to hunt down the shipwrecked survivors and assimilate them into the planet’s ecosystem. By playing your Hunt cards and activating the powers of Artemia, you repeatedly attack the Hunted to wear down their will and inescapably bind them to the planet.

== Place cards ==

The planet Artemia is made up of 10 different Place cards. Each Place card has a number, a name and a power that can be activated by the Hunted. '''The place cards are horizontally or vertically adjacent.'''

Each Hunted begins the game with the 5 basic Place cards (Lair, Jungle, River, Beach and Rover) and may explore new places during the game (Swamp, Shelter, Wreck, Source and Artefact).

== Hunt cards ==

Hunt cards increase the chances of the Creature of assimilating the Hunted. Each Hunt card shows a power that can be activated by the Creature and the phase in which that power may be played. Some also show a Target or Artemia symbol.

Hunt Cards may be played at any time during the phase shown on the card and are discarded after use. '''The Creature may only play one Hunt card per turn''' unless specified otherwise.

If a Hunt card with the Target symbol is played, '''the Creature assigns its effects by placing the Target token on one of the 10 Place cards''' that form the planet. If the Creature plays 2 Hunt cards with this symbol during a turn, apply both effects to the targeted place.

If a Hunt card with the Artemia symbol is played, '''the Creature assigns its effects by placing the Artemia token on one of the 10 Place cards''' that form the planet. If the Creature plays 2 Hunt cards with this symbol during a turn, apply both effects.

== Survival cards ==

Survival cards increase the chances of the Hunted of resisting the Creature’s attacks until the arrival of the Rescue mission. Each Survival card shows a power that can be activated by the Hunted and the phase in which that power may be played.

Survival cards may be played at any time during the phase shown on the card and are discarded after use. '''Each Hunted may only play one Survival card per turn''' even if caught by the Creature. There is no limit to the number of Survival cards that a Hunted may hold.

'''Hunt and Survival cards used during the same phase take effect in the order in which they are played.'''

'''The effects of Hunt and Survival cards are limited to the current game turn''' and they may change the general rules.

== Playing the game ==

Each turn takes place over 4 phases: Exploration, Hunting, Reckoning and End-of-Turn Actions. Proceed as follows:

=== Phase 1: Exploration ===

'''The Hunted simultaneously play one Place card''' each from their hand by placing it face down in front of them. They may communicate, but only aloud. Players may bluff, but they may not reveal their cards to each other. '''Playing a Place card is mandatory.'''

Before playing a Place card, a Hunted may choose to do the following:

- '''Resist''': the player forfeits 1 or 2 Will counters to take back 2 or 4 Place cards of his choice, respectively, from his discard pile. If in doing so a Hunted loses his third Will counter, he
must '''Give Up'''.

- '''Give Up''': the player regains all of his Will counters and takes back all of his discarded Place cards. Giving up, however, lets the Creature assimilate the Hunted faster. '''Each time a Hunted gives up during this phase, immediately move forward the Assimilation counter by one space.'''

=== Phase 2 : Hunting ===

The Creature may place the following tokens on the Place cards that make up Artemia:

- The Creature token.

- The Target token if the target symbol is on a Hunt card played.

- The Artemia token if the Artemia Symbol is on a Hunt card played '''AND/OR''' on the space under the Rescue counter.

'''The Hunt tokens can be placed on the same place to stack their effects.'''

=== Phase 3 : Reckoning ===

'''The Hunted simultaneously reveal their Place card.''' The phase should then proceed as follows:

- Starting with the player to the left of the Creature, each Hunted who explores a place without a Hunt token may immediately '''use the place’s power''' OR '''take back 1 Place card of his choice from his discard pile'''. If a place’s power is ineffective as a result of a Hunt card, the Hunted may not take back a discarded Place card.

- Each Hunted who explores the place where the Target token is located is subjected to the '''effect of the Hunt card'''. He may then '''use the power on the Place card''' OR '''take back 1 Place card of his choice from his discard pile'''. If a place’s power is ineffective as a result of a Hunt card, the Hunted may not take back a discarded Place card.

- Each Hunted who explores the place where the Artemia token is located '''discards 1 Place card from his hand'''. The '''place’s power may not be used''' and the Hunted may not take back a discarded Place card.

- Each Hunted who explores the place where the Creature token is located '''loses 1 Will counter'''. '''Immediately move the Assimilation counter forward 1 space regardless of the number of Hunted caught.''' The place’s power may not be used and the Hunted may not take back a discarded Place card.

'''During this phase, if at least one of the Hunted loses his third Will counter, move the Assimilation counter forward by 1 space.''' Then these Hunted take back all of their Place cards, as well as their 3 Will counters.

=== Phase 4 : End-of-turn actions ===

'''Each Hunted''' discards the Place card played, face up. The Creature must always be able to see the figures on all discarded Place cards. '''The Creature''' takes back its Hunt tokens and draws Hunt cards up to a hand of 3.

'''Move the Rescue counter forward 1 space''' and begin again at Phase 1: Exploration.

== End of game ==
'''The Creature wins''' immediately if the Assimilation counter reaches the Victory space first. With their will sapped, all of the Hunted have been assimilated. They are now part of the planet.

'''The Hunted win''' immediately if the Rescue counter reaches the Victory space first. A rescue mission arrives to extract the survivors from this hostile planet.

== FAQ ==

=== THE LAIR ===
If a Hunted chooses to retrieve his discarded Place cards, he does not retrieve the Lair because during the Reckoning phase, the Lair is not yet in the player’s discarded cards.

=== THE BEACH ===
Use of the Beach is limited to once per turn regardless of the number of Hunted exploring the Beach: either charge the Marker (place the Marker token on the Beach), or activate the Marker (remove the Marker token from the Beach and move the Rescue counter forward by 1 space). If two or more Hunted explore the Beach, one of them may use the power of the Beach and the others may take back 1 Place card of their choice from their discard pile. The power of the Beach may stack with that of the Wreck.

=== THE WRECK ===
Use of the Wreck is limited to once per turn regardless of the number of Hunted exploring the Wreck. If two or more Hunted explore the Wreck, one of them may use the power of the Wreck and the others may take back 1 Place card of their choice from their discard pile. The power of the Wreck may stack with that of the Beach.

=== THE ARTEFACT ===
The 2 Place cards played are resolved one by one in the order of the player’s choice, following the rules of Phase 3: Reckoning. The power of the Artefact may not be copied by a place’s power, nor by a Survival card.

Gamehelpnotalone

2019-04-09T09:17:57Z

Tilalilalou:

Gamehelpnotalone

2019-04-09T09:12:24Z

Tilalilalou:

Gamehelpnotalone

2019-04-09T09:08:28Z

Tilalilalou: Created page with "== Object of the game == NOT ALONE is an asymmetrical card game, with one player (the Creature) playing against the other players (the Hunted). If you play as one of the Hunt..."

Gamehelpthroughtheages

2019-03-19T08:25:08Z

Tilalilalou:

During your turn, you may spend your '''actions points''' to:
* pick cards from the card rows (if you have room in your hand)
** Wonders cost an additional civil action for each wonder you have finished
* play cards to your tableau
* increase your population
* build/upgrade farms, mines, or urban buildings
* build/upgrade military units
** Play tactics cards to increase your military strength. As long as all units contributing to the tactics card are within one age of the card, you get the greater of the two values.

'''Yellow counters''' represent your population. They can be in one of three places:
* on the cards on your tableau
* on your available worker pool
* on your "yellow bank" -- when this is empty, you can no longer increase your available population

'''Blue counters''' represent food or resources. They can be in three places:
* on your farms or mines
* on your "blue bank" -- when this is empty, you can no longer produce food or resources
* on your wonder, marking how far along it's construction is

Building up your civilisation:
* '''Food''' lets you move workers from your yellow bank to your available worker pool.
* '''Resources''' let you move workers from your available worker pool to a card on your tableau.
* '''Science''' (light bulbs) lets you move cards from your hand to your tableau.
* When your population grows, you will need to produce more '''happiness''' or your workers will stop working.
* Producing '''culture''' will earn you victory points.
* Producing more '''military strength''' will protect you from raids or wars.

There are 3 versions of ''Through the Ages'':
* ''Simple'' plays through Age I
* ''Advanced'' plays through Age II, and introduces political actions (colonies and raids), unhappiness, and corruption
* ''Complete'' plays through Age III, and introduces wars
In the ''Simple'' and ''Advanced'' versions, the game ends immediately when there are no more cards to replenish the deck and both players have played an equal number of turns.

In the Advanced and Complete games, '''additional points are scored at the end of the game''' according to special event cards. But at the end of the Simple game, additional points are scored the same way every game:
* 2 culture scored per 1 Strength (military)
* 2 culture scored per Happy Face
* 2 culture scored per level 1 technology in play
* 1 culture scored per food or resource production per turn
* 1 culture scored per 1 Science Rating (science gained per turn)

Deck

2019-02-20T09:42:36Z

Tilalilalou: /* auto-reshuffle */

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

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

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 card to create. "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, 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 )'''

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.

'''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
* to_location: where to put the cards
* from_location (optional): if specified, only cards with given "location_arg" are moved.
* to_location (optional): if specified, cards moved "location_arg" is set to given value. Otherwise location_arg is set to zero.

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

If some cards are not found or if some cards 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".

=== 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 "$mydeck->autoreshuffle = true" during the setup of the component.

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

Deck

2019-02-20T09:38:21Z

Tilalilalou: /* auto-reshuffle */

2019-01-31T21:39:42Z

Tilalilalou: /* Complete stock component reference */

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

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

With create, you create a new stock component.

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

(See ''Hearts'' example above).

'''count():'''

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

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

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

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

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

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

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

<pre>
// Specify that there are 10 image items per row in images used in "myStockObject" control.
this.myStockObject.image_items_per_row = 10;
</pre>

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

Add an item to the stock, with the specified type, 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 addressed 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'''.

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

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

Remove an item of the specific type from the stock.

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

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

Remove an item with a specific ID from the stock.

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

'''removeAll()'''

Remove all items from the stock.

'''getPresentTypeList()'''

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

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

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

'''resetItemsPosition()'''

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

'''item_margin'''

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

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

'''changeItemsWeight( newWeights )'''

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

Items are immediately re-sorted with the new weight.

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

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

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

'''setSelectionMode( mode )'''

For each stock control, you can specify a selection mode:
* 0: no item can be selected by the player.
* 1: a maximum of one item can be selected by the player at 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). You can override this class in the css file for your game.

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

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

'''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 )
{
// This method is called when myStockControl selected items changed
var items = this.myStockControl.getSelectedItems();

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

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

'''getSelectedItems()'''

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

'''getUnselectedItems()'''

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

'''getAllItems()'''

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

'''getItemDivId(id)'''

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

'''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 over 20% of the width of the previous item. 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.

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

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

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

Deck

2019-01-31T17:18:20Z

Tilalilalou: /* Create a new Deck component */

Translations

2013-05-21T21:36:02Z

Tilalilalou: /* On server side (PHP) */

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

== How translation works? ==

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

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

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

== What should be translated? ==

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

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

== Focus on translating notifications ==

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

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

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

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

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

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

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

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

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

== On client side (Javascript) ==

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

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

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

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

== On server side (PHP) ==

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

// ... notice the use of BgaUserException that signals that this exception is "expected". In theory, all exception that are expected should be translated.
</pre>

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

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

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

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

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

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

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

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

Main game logic: yourgamename.game.php

2013-05-21T16:24:52Z

Tilalilalou: /* Zombie mode */

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

== File Structure ==

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

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

== Accessing player informations ==

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

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

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

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

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

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

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

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

== Accessing database ==

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

'''IMPORTANT'''

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

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

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

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

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

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

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

</pre>

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

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

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

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

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

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

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

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

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

</pre>

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

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

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

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

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

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

</pre>

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

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

== Use globals ==

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

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

'''initGameStateLabels'''

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

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

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

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

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

'''getGameStateValue( $value_label )'''

Retrieve the current value of a global.

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

Set the current value of a global.

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

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

Return the final value of the global.

== Game states and active players ==

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

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

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

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

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

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

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

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

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

== Players turn order ==

'''getNextPlayerTable()'''

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

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

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

'''getPrevPlayerTable()'''

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

'''getPlayerAfter( $player_id )'''

Get player playing after given player in natural playing order.

'''getPlayerBefore( $player_id )'''

Get player playing before given player in natural playing order.

== Notify players ==

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

'''IMPORTANT'''

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

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

Send a notification to all players of the game.

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

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

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

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

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

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

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

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

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

Complete notifyAllPlayers example (from "Reversi"):

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

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

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

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

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

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

== Game statistics ==

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

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

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

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

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

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

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

Set a statistic value.

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

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

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

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

== Translations ==

See [[Translations]]

== Manage player scores and Tie breaker ==

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

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

Examples:
<pre>

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

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

</pre>

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

'''Tie breaker'''

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

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

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

When you are using "player_score_aux" functionality, you must describe the formula to use in your Constructor method like this:

<pre>
$this->tie_breaker_description = self::_("Describe here your tie breaker formula");
</pre>

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

== Reflexion time ==

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

== Managing errors and exceptions ==

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

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

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

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

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

== Zombie mode ==

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

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

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

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

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

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

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

if( $statename == 'myFirstGameState'
|| $statename == 'my2ndGameState'
|| $statename == 'my3rdGameState'
....
)
{
$this->gamestate->nextState( "zombiePass" );
}
else
throw new BgaSystemVisibleException( "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.