Board Game Arena - User contributions [en]

Gamehelphandandfoot

2026-03-22T13:00:21Z

RavingWanderer: de-emphasizing less common variants and those not available on BGA

'''Hand and Foot''' is a traditional card game for 2 or more players, acting either individually or in teams. It uses a large number of card decks (typically one or two more than the number of players), and is a rummy-style meld-building game based on Canasta.
[[Category:Card games]]
==Game duration and number of players==
A game is divided into ''rounds'', each consisting of the play of one deal of cards. Play can either be for a set number of rounds (typically 4), or until a team reaches a threshold score. The team with the highest score wins the game.

A typical four-round game with four players takes about two hours to complete when played in person. On BGA it is more typically 45 minutes to one hour.

==Round setup==
Players are seated so that partners are opposite each other at the table. If teams have more than two players, they are seated so team members are equidistant from each other.

The number of decks used is typically one or two more than the number of players, with the jokers included. For faster play, non-joker cards with proper card backs can also be mixed in; in BGA this is represented as allowing more than two joker per deck. The decks are all shuffled together, and each player is dealt two piles of cards. House rules differ on the number of cards: some dictate the piles are 11 cards, others say 13. One pile is not looked at, and is the ''foot''. The other is picked up by the player and is the ''hand''.

The undealt cards are stacked into a ''draw pile'', while a ''discard pile'' is formed next to it to accumulated discarded cards.

==Game objective==

The objective of the game is to create ''melds'' consisting of 3-7 (or sometimes more, depending on house rules) cards of the same rank, possibly including ''wild cards''. Wild cards are deuces and jokers. Melds of seven cards (or more) are considered to be ''complete'', and may be referred to as ''books''; bonuses are awarded for these melds. Melds with less than 7 cards are considered ''open''. A book with no wild cards is considered ''clean'' or ''red'', and will score a higher bonus than a ''dirty'' or ''black'' book, which has at least one wild card. If the house rules allow or require, a meld of all wild cards may be formed, which will score an even higher bonus than clean books.

A team must reach a predetermined ''contract'' before a round can be ended. The contract is typically for a set number of clean, dirty, and wild books, and is the same for each team and each round of play. A common contract for teams of two is two each clean and dirty books.

==Scoring and card valuation==
Cards are valued by their rank:
*Jokers are worth 50 points
*Aces and deuces are worth 20 points
*8 through King are worth 10 points
*4 through 7 are worth 5 points
The values of 3s depend on house rules. In common variants, red 3s are worth either 100 or 300 points. Black 3s are typically worth 5 points against you, and cannot be melded or taken from the top of the discard pile (but see [[#Taking the discard|Taking the discard]] below). In some variants Black 3s count 100 points against you, and in others they can be melded, but still count againsts you.

Cards played on the board are scored for the team, while those left in the hand (and foot) are scored against the team.

===Going out and meld completion bonuses===
The team that goes out to end a round of play is awarded 100 or 200 points for doing so. If the draw pile is exhausted, the round ends and no team gets this bonus.

Meld bonuses are awarded when a meld reaches seven cards in length, and is denoted in the BGA version of the game by displaying the meld sideways. The most common meld completion bonuses are:
* Clean books score 500
* Dirty books score 300
* Wild books score 1500
Less common scores (not available as options on BGA):
* Clean book of 7s scores 1500
==Order of play==
* High card begins the play, or the player to the dealer's left begins
* Play goes clockwise around the table
* Play and Discard
* Either draw two cards, or take the discard (you cannot take the discard which consists of the top 3 cards if your team has not melded your initial meld (1st round-50pts) (2nd round (90 points) (3rd Round 120 points) ( 4th round 150 points)
* Optionally create new melds for the team, or play cards to existing team melds, assuming ''opening criteria'' are met
* If still holding cards, discard one to end play.

If the player runs out of cards without discarding, they can pick their foot and immediately continue playing from it; this is called ''running to the foot''. If the player discards their last card, they can pick up their foot, but not play from it until their next turn; this is called ''walking''.

The round ends when a team has completed the required contract, and one of its players plays out both their hand and their foot.

A team must meet certain criteria in order to open play on their board. The requirement is that the opening player must put down cards with a minimum card point value, and typically varies by either which round of play (increasing with each successive round), or by the team's score. The most common opening criteria are:
* Round 1: 50 points to open
* Round 2: 90 points to open
* Round 3: 120 points to open
* Round 4: 150 points to open
If a tie-breaking fifth round is needed, it will also require 150 points to open. The point score does not include meld completion bonuses, or any played red 3s. For example, a completed book of 5s scores 35 points, with a bonus of 500 points for being complete, but is insufficient to open even round 1.

===Playing red 3s===
The most common game variants include the automatic play of red 3s. When it is a player's turn, any red 3s in the hand are played and replaced with new cards. This occurs *before* the player draws or takes the discard. In discard-only variants, red 3s can only be discarded, and cannot be taken from the discard pile.

===Drawing cards===
Draw 2 cards. After play discard 1 card.

===Taking the discard===
If the player is allowed by the house rules, they may pick up the top discard. Common house rules require the player to (1) have two cards of the same rank in their hand, and (2) be able to immediately play all three cards to the board. Among other things, this means that their team either (a) has already opened its board, or (b) the player taking the discard can meet the opening criteria for the round. It also means that the top card is not a black 3, or any other card where it is forbidden by house rules to take it. (Some house variants forbid the taking of wild cards, and house rules requiring red 3s to be discarded also typically forbid their taking.)

Once the player has taken and played the discard and associated meld cards, most rules require the taking of additional cards from the discard pile. This is generally six cards, or the entire pile if it is less, but there are house rules that require the pile to have at least six more cards in it, or that require the taking of the entire discard pile in the manner of traditional Canasta rules. A discard pile rich in black 3s can discourage the taking of discards.

===Playing cards===
Playing cards to the board consists of selecting a group of matching cards (all of the same rank with optional wild cards), and clicking on either the "New Meld" panel or the meld of the given rank on the team's meld board. If melds are limited in size, you will not be allowed to make a meld have more than seven cards.

You can have only one meld of a given rank open at any time. In order to create a meld, you must have at least three cards to play to it. You must always have more non-wild than wild cards in a meld, and common house rules limit the number of wild cards in a completed meld to either 2 or 3. The BGA version of the game enforces this by a "ratio rule", requiring a certain percentage of the cards in a meld at any given time to be non-wild.

The card plays you make (other than the required play of red 3s) are not shown to other players until one of several actions take place. These actions include:
*Discarding to end your turn
*Playing out, either to end the round or to run to your foot
*Taking extra discards

It is possible to ''undo'' moves up the last instance of one of these in your turn. This may become necessary for three reasons. First, if you attempt to open, but do not have sufficient points to make the opening criteria, you must undo your moves and make a discard instead. Second, you cannot play the last card from your foot unless your team has made the contracted melds. The game will not allow you to play out, so you must undo your moves. Third, if the game rules are that you must be able to play all your cards in your foot without a discard, but your last card is not playable.

===Discarding===
To discard, select a single card, and place it on the discard pile. If it is the last card of your foot, you will not be allowed to discard it if your team does not have the contracted melds. In that case, you will have to undo your moves, and play so as to have at least one card remaining in your hand after discarding.

=== Permission to go out ===
If a player sees that they are able to go out, after drawing, the player may ask "Partner,may I go out?" The partner must answer "Yes" or "No," and the answer is binding.

==Round and game summaries==
At the end of each round, a scoring summary is prepared. At the end of the game, the report includes all of the game rounds.

Main game logic: Game.php

2020-10-27T14:32:56Z

RavingWanderer: /* States functions */ add to checkAction which player is being checked

{{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 is...?
* 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 ([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.

; getActivePlayerColor()
: This function does not seems to exist in API, if you need it here is implementation
function getActivePlayerColor() {
$player_id = self::getActivePlayer();
$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 )
: Idem than previous one, but raise an exception if the collection is empty

; 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_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 79 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 (triggers onUpdateActionButtons).
: 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. Do not use method if you going to do some more chages in active player list, i.e. if you want to take away multi-active right after, use setPlayersMultiactive instead.

Example of usage:
<pre>
function st_MultiPlayerInit() {
$this->gamestate->setAllPlayersMultiactive();
}
</pre>
And this is declaration of state:
<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' => 'st_MultiPlayerInit',
'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 who's 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. Here seems also the "0" missing.

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

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

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

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

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

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

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

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

; 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( $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()
: 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' ), // deutsch
'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' ), // portugese
'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.

Gamehelphandandfoot

2020-09-13T21:49:49Z

RavingWanderer: more on undo

'''Hand and Foot''' is a traditional card game for 2 or more players, acting either individually or in teams. It uses a large number of card decks (typically one or two more than the number of players), and is a rummy-style meld-building game based on Canasta.

==Game duration and number of players==
A game is divided into ''rounds'', each consisting of the play of one deal of cards. Play can either be for a set number of rounds (typically 4), or until a team reaches a threshold score. The team with the highest score wins the game.

A typical four-round game with four players takes about two hours to complete. The BGA version of the game supports from two to seven individual players, and up to 12 when playing in teams.

==Round setup==
Players are seated so that partners are opposite each other at the table. If teams have more than two players, they are seated so team members are equidistant from each other.

The number of decks used is typically one or two more than the number of players, with the jokers included. For faster play, non-joker cards with proper card backs can also be mixed in; in BGA this is represented as allowing more than two joker per deck. The decks are all shuffled together, and each player is dealt two piles of cards. House rules differ on the number of cards: some dictate the piles are 11 cards, others say 13. One pile is not looked at, and is the ''foot''. The other is picked up by the player and is the ''hand''.

The undealt cards are stacked into a ''draw pile''. Optionally, one card is turned over to start the ''discard pile''.

==Game objective==

The objective of the game is to create ''melds'' consisting of 3-7 (or sometimes more, depending on house rules) cards of the same rank, possibly including ''wild cards''. Wild cards are deuces and jokers. Melds of seven cards (or more) are considered to be ''complete'', and may be referred to as ''books''; bonuses are awarded for these melds. Melds with less than 7 cards are considered ''open''. A book with no wild cards is considered ''clean'' or ''red'', and will score a higher bonus than a ''dirty'' or ''black'' book, which has at least one wild card. If the house rules allow or require, a meld of all wild cards may be formed, which will score an even higher bonus than clean books. Melds are depicted in the BGA version of the game by red cards with blue borders if they are clean, black cards with brown borders if they are dirty, and jokers bordered by gold cards if they are wild.

A team must reach a predetermined ''contract'' before a round can be ended. The contract is typically for a set number of clean, dirty, and wild books, and is the same for each team and each round of play. A common contract for teams of two is two each clean and dirty books, and one wild book.

==Scoring and card valuation==
Cards are valued by their rank:
*Jokers are worth 50 points
*Aces and deuces are worth 20 points
*8 through King are worth 10 points
*4 through 7 are worth 5 points
The values of 3s depend on house rules. In common variants, red 3s are worth 100 points, and are played automatically and replaced with a new card when it is the player's turn. Black 3s are typically worth 5 points, and cannot be melded at all, or taken from the top of the discard pile (but see [[#Taking the discard|Taking the discard]] below).

Cards played on the board are scored for the team, while those left in the hand (and foot) are scored against the team.

===Going out and meld completion bonuses===
The team that goes out to end a round of play is awarded 100 points for doing so. If the draw pile is exhausted, the round ends and no team gets this bonus.

Meld bonuses are awarded when a meld reaches seven cards in length, and is denoted in the BGA version of the game by displaying the meld sideways. The most common meld completion bonuses are:
* Clean books score 500
* Dirty books score 300
* Wild books score 1500

==Order of play==
The player to the left of the dealer begins play. Each player's turn includes the following steps:
* Play and replace any red 3s in the hand
* Either draw two cards (playing and replacing drawn red 3s if necessary), or take the discard
* Optionally create new melds for the team, or play cards to existing team melds, assuming ''opening criteria'' are met
* If still holding cards, discard one

If the player runs out of cards without discarding, they can pick their foot and immediately continue playing from it; this is called ''running to the foot''. If the player discards their last card, they can pick up their foot, but not play from it until their next turn; this is called ''walking''.

The round ends when a team has completed the required contract, and one of its players plays out both their hand and their foot. Some house rules require the last card to be discarded, while others allow it to be played.

===Opening criteria===
A team must meet certain criteria in order to open play on their board. The requirement is that the opening player must put down cards with a minimum card point value, and typically varies by either which round of play (increasing with each successive round), or by the team's score. The most common opening criteria are:
* Round 1: 50 points to open
* Round 2: 90 points to open
* Round 3: 120 points to open
* Round 4: 150 points to open
If a tie-breaking fifth round is needed, it will also require 150 points to open. The point score does not include meld completion bonuses, or any played red 3s. For example, a completed book of 5s scores 35 points, with a bonus of 500 points for being complete, but is insufficient to open even round 1.

===Playing red 3s===
A common house rule requires that red 3s are played into a special pile, and immediately replaced ''when it is the player's turn''. This may occur before the draw when the player first plays from either their hand or foot, or when they draw a red 3. Red 3s played in this manner do not count toward opening criteria.

===Drawing cards===
Once a player has played any red 3s in their hand, they may choose (or be forced to) draw cards. This takes place in BGA by clicking on the draw pile, and delivers two cards into the hand.

===Taking the discard===
If the player is allowed by the house rules, they may pick up the top discard. Common house rules require the player to (1) have two cards of the same rank in their hand, and (2) be able to immediately play all three cards to the board. Among other things, this means that his team either (a) has already opened its board, or (b) the player taking the discard can meet the opening criteria for the round. It also means that the top card is not a black 3, or any other card where it is forbidden by house rules to take it. (Some house variants forbid the taking of wild cards, and house rules requiring red 3s to be discarded also typically forbid their taking.)

Once the player has taken and played the discard and associated meld cards, most rules require the taking of additional cards from the discard pile. This is generally six cards, or the entire pile if it is less, but there are house rules that require the pile to have at least six more cards in it, or that require the taking of the entire discard pile in the manner of traditional Canasta rules. A discard pile rich in black 3s can discourage the taking of discards.

===Playing cards===
Playing cards to the board consists of selecting a group of matching cards (all of the same rank with optional wild cards), and clicking on either the "New Meld" panel or the meld of the given rank on the team's meld board. If melds are limited in size, you will not be allowed to make a meld have more than seven cards.

You can have only one meld of a given rank open at any time. In order to create a meld, you must have at least three cards to play to it. You must always have more non-wild than wild cards in a meld, and common house rules limit the number of wild cards in a completed meld to either 2 or 3. The BGA version of the game enforces this by a "ratio rule", requiring a certain percentage of the cards in a meld at any given time to be non-wild.

The card plays you make (other than the required play of red 3s) are not shown to other players until one of several actions take place. These actions include:
*Discarding to end your turn
*Playing out, either to end the round or to run to your foot
*Taking extra discards

It is possible to ''undo'' moves up the last instance of one of these in your turn. This may become necessary for three reasons. First, if you attempt to open, but do not have sufficient points to make the opening criteria, you must undo your moves and make a discard instead. Second, you cannot play the last card from your foot unless your team has made the contracted melds. The game will not allow you to play out, so you must undo your moves. Third, if the game rules require you to discard the last card from your foot, you will not be allowed to play it. If you do not have the contract, you will also not be allowed to discard it. In the latter two cases, you may be able to repeat ''some'' of the undone moves, but you must be able to make a valid discard to end your turn.

===Discarding===
To discard, select a single card, and click on the discard pile. If it is the last card of your foot, you will not be allowed to discard it if your team does not have the contracted melds. In that case, you will have to undo your moves, and play so as to have at least one card remaining in your hand after discarding.

==Round and game summaries==
At the end of each round, a scoring summary is displayed, showing how each team made its points in the round. At the end of the game, the report includes all of the game rounds.

Gamehelphandandfoot

2020-09-10T19:09:56Z

RavingWanderer: more variant stuff

'''Hand and Foot''' is a traditional card game for 2 or more players, acting either individually or in teams. It uses a large number of card decks (typically one or two more than the number of players), and is a rummy-style meld-building game based on Canasta.

==Game duration and number of players==
A game is divided into ''rounds'', each consisting of the play of one deal of cards. Play can either be for a set number of rounds (typically 4), or until a team reaches a threshold score. The team with the highest score wins the game.

A typical four-round game with four players takes about two hours to complete. The BGA version of the game supports from two to seven individual players, and up to 12 when playing in teams.

==Round setup==
Players are seated so that partners are opposite each other at the table. If teams have more than two players, they are seated so team members are equidistant from each other.

The number of decks used is typically one or two more than the number of players, with the jokers included. For faster play, non-joker cards with proper card backs can also be mixed in; in BGA this is represented as allowing more than two joker per deck. The decks are all shuffled together, and each player is dealt two piles of cards. House rules differ on the number of cards: some dictate the piles are 11 cards, others say 13. One pile is not looked at, and is the ''foot''. The other is picked up by the player and is the ''hand''.

The undealt cards are stacked into a ''draw pile''. Optionally, one card is turned over to start the ''discard pile''.

==Game objective==

The objective of the game is to create ''melds'' consisting of 3-7 (or sometimes more, depending on house rules) cards of the same rank, possibly including ''wild cards''. Wild cards are deuces and jokers. Melds of seven cards (or more) are considered to be ''complete'', and may be referred to as ''books''; bonuses are awarded for these melds. Melds with less than 7 cards are considered ''open''. A book with no wild cards is considered ''clean'' or ''red'', and will score a higher bonus than a ''dirty'' or ''black'' book, which has at least one wild card. If the house rules allow or require, a meld of all wild cards may be formed, which will score an even higher bonus than clean books. Melds are depicted in the BGA version of the game by red cards with blue borders if they are clean, black cards with brown borders if they are dirty, and jokers bordered by gold cards if they are wild.

A team must reach a predetermined ''contract'' before a round can be ended. The contract is typically for a set number of clean, dirty, and wild books, and is the same for each team and each round of play. A common contract for teams of two is two each clean and dirty books, and one wild book.

==Scoring and card valuation==
Cards are valued by their rank:
*Jokers are worth 50 points
*Aces and deuces are worth 20 points
*8 through King are worth 10 points
*4 through 7 are worth 5 points
The values of 3s depend on house rules. In common variants, red 3s are worth 100 points, and are played automatically and replaced with a new card when it is the player's turn. Black 3s are typically worth 5 points, and cannot be melded at all, or taken from the top of the discard pile (but see [[#Taking the discard|Taking the discard]] below).

Cards played on the board are scored for the team, while those left in the hand (and foot) are scored against the team.

===Going out and meld completion bonuses===
The team that goes out to end a round of play is awarded 100 points for doing so. If the draw pile is exhausted, the round ends and no team gets this bonus.

Meld bonuses are awarded when a meld reaches seven cards in length, and is denoted in the BGA version of the game by displaying the meld sideways. The most common meld completion bonuses are:
* Clean books score 500
* Dirty books score 300
* Wild books score 1500

==Order of play==
The player to the left of the dealer begins play. Each player's turn includes the following steps:
* Play and replace any red 3s in the hand
* Either draw two cards (playing and replacing drawn red 3s if necessary), or take the discard
* Optionally create new melds for the team, or play cards to existing team melds, assuming ''opening criteria'' are met
* If still holding cards, discard one

If the player runs out of cards without discarding, they can pick their foot and immediately continue playing from it; this is called ''running to the foot''. If the player discards their last card, they can pick up their foot, but not play from it until their next turn; this is called ''walking''.

The round ends when a team has completed the required contract, and one of its players plays out both their hand and their foot. Some house rules require the last card to be discarded, while others allow it to be played.

===Opening criteria===
A team must meet certain criteria in order to open play on their board. The requirement is that the opening player must put down cards with a minimum card point value, and typically varies by either which round of play (increasing with each successive round), or by the team's score. The most common opening criteria are:
* Round 1: 50 points to open
* Round 2: 90 points to open
* Round 3: 120 points to open
* Round 4: 150 points to open
If a tie-breaking fifth round is needed, it will also require 150 points to open. The point score does not include meld completion bonuses, or any played red 3s. For example, a completed book of 5s scores 35 points, with a bonus of 500 points for being complete, but is insufficient to open even round 1.

===Playing red 3s===
A common house rule requires that red 3s are played into a special pile, and immediately replaced ''when it is the player's turn''. This may occur before the draw when the player first plays from either their hand or foot, or when they draw a red 3. Red 3s played in this manner do not count toward opening criteria.

===Drawing cards===
Once a player has played any red 3s in their hand, they may choose (or be forced to) draw cards. This takes place in BGA by clicking on the draw pile, and delivers two cards into the hand.

===Taking the discard===
If the player is allowed by the house rules, they may pick up the top discard. Common house rules require the player to (1) have two cards of the same rank in their hand, and (2) be able to immediately play all three cards to the board. Among other things, this means that his team either (a) has already opened its board, or (b) the player taking the discard can meet the opening criteria for the round. It also means that the top card is not a black 3, or any other card where it is forbidden by house rules to take it. (Some house variants forbid the taking of wild cards, and house rules requiring red 3s to be discarded also typically forbid their taking.)

Once the player has taken and played the discard and associated meld cards, most rules require the taking of additional cards from the discard pile. This is generally six cards, or the entire pile if it is less, but there are house rules that require the pile to have at least six more cards in it, or that require the taking of the entire discard pile in the manner of traditional Canasta rules. A discard pile rich in black 3s can discourage the taking of discards.

===Playing cards===
Playing cards to the board consists of selecting a group of matching cards (all of the same rank with optional wild cards), and clicking on either the "New Meld" panel or the meld of the given rank on the team's meld board. If melds are limited in size, you will not be allowed to make a meld have more than seven cards.

You can have only one meld of a given rank open at any time. In order to create a meld, you must have at least three cards to play to it. You must always have more non-wild than wild cards in a meld, and common house rules limit the number of wild cards in a completed meld to either 2 or 3. The BGA version of the game enforces this by a "ratio rule", requiring a certain percentage of the cards in a meld at any given time to be non-wild.

You cannot play the last card from your foot unless your team has made the contracted melds. It is for this reason you can ''undo'' your moves.

===Discarding===
To discard, select a single card, and click on the discard pile. If it is the last card of your foot, you will not be allowed to discard it if your team does not have the contracted melds. In that case, you will have to undo your moves, and play so as to have at least one card remaining in your hand after discarding.

==Round and game summaries==
At the end of each round, a scoring summary is displayed, showing how each team made its points in the round. At the end of the game, the report includes all of the game rounds.

Gamehelphandandfoot

2020-09-10T19:03:24Z

RavingWanderer: rule summary

'''Hand and Foot''' is a traditional card game for 2 or more players, acting either individually or in teams. It uses a large number of card decks (typically one or two more than the number of players), and is a rummy-style meld-building game based on Canasta.

==Game duration and number of players==
A game is divided into ''rounds'', each consisting of the play of one deal of cards. Play can either be for a set number of rounds (typically 4), or until a team reaches a threshold score. The team with the highest score wins the game.

A typical four-round game with four players takes about two hours to complete. The BGA version of the game supports from two to seven individual players, and up to 12 when playing in teams.

==Round setup==
Players are seated so that partners are opposite each other at the table. If teams have more than two players, they are seated so team members are equidistant from each other.

The number of decks used is typically one or two more than the number of players, with the jokers included. For faster play, non-joker cars with proper card backs can also be mixed in. The decks are all shuffled together, and each player is dealt two piles of cards. House rules differ on the number of cards: some dictate the piles are 11 cards, others say 13. One pile is not looked at, and is the ''foot''. The other is picked up by the player and is the ''hand''.

The undealt cards are stacked into a ''draw pile''. Optionally, one card is turned over to start the ''discard pile''.

==Game objective==

The objective of the game is to create ''melds'' consisting of 3-7 (or sometimes more, depending on house rules) cards of the same rank, possibly including ''wild cards''. Wild cards are deuces and jokers. Melds of seven cards (or more) are considered to be ''complete'', and may be referred to as ''books''; bonuses are awarded for these melds. Melds with less than 7 cards are considered ''open''. A book with no wild cards is considered ''clean'' or ''red'', and will score a higher bonus than a ''dirty'' or ''black'' book, which has at least one wild card. If the house rules allow or require, a meld of all wild cards may be formed, which will score an even higher bonus than clean books. Melds are depicted in the BGA version of the game by red cards with blue borders if they are clean, black cards with brown borders if they are dirty, and jokers bordered by gold cards if they are wild.

A team must reach a predetermined ''contract'' before a round can be ended. The contract is typically for a set number of clean, dirty, and wild books, and is the same for each team and each round of play. A common contract for teams of two is two each clean and dirty books, and one wild book.

==Scoring and card valuation==
Cards are valued by their rank:
*Jokers are worth 50 points
*Aces and deuces are worth 20 points
*8 through King are worth 10 points
*4 through 7 are worth 5 points
The values of 3s depend on house rules. In common variants, red 3s are worth 100 points, and are played automatically and replaced with a new card when it is the player's turn. Black 3s are typically worth 5 points, and cannot be melded at all, or taken from the top of the discard pile (but see [[#Taking the discard|Taking the discard]] below).

Cards played on the board are scored for the team, while those left in the hand (and foot) are scored against the team.

===Going out and meld completion bonuses===
The team that goes out to end a round of play is awarded 100 points for doing so. If the draw pile is exhausted, the round ends and no team gets this bonus.

Meld bonuses are awarded when a meld reaches seven cards in length, and is denoted in the BGA version of the game by displaying the meld sideways. The most common meld completion bonuses are:
* Clean books score 500
* Dirty books score 300
* Wild books score 1500

==Order of play==
The player to the left of the dealer begins play. Each player's turn includes the following steps:
* Play and replace any red 3s in the hand
* Either draw two cards, or take the discard
* Optionally create new melds for the team, or play cards to existing team melds, assuming ''opening criteria'' are met
* If still holding cards, discard one

If the player runs out of cards without discarding, they can pick their foot and immediately continue playing from it; this is called ''running to the foot''. If the player discards their last card, they can pick up their foot, but not play from it until their next turn; this is called ''walking''.

The round ends when a team has completed the required contract, and one of its players plays out both their hand and their foot. Some house rules require the last card to be discarded, while others allow it to be played.

===Opening criteria===
A team must meet certain criteria in order to open play on their board. The requirement is that the opening player must put down cards with a minimum card point value, and typically varies by either which round of play (increasing with each successive round), or by the team's score. The most common opening criteria are:
* Round 1: 50 points to open
* Round 2: 90 points to open
* Round 3: 120 points to open
* Round 4: 150 points to open
If a tie-breaking fifth round is needed, it will also require 150 points to open. The point score does not include meld completion bonuses, or any played red 3s. For example, a completed book of 5s scores 35 points, with a bonus of 500 points for being complete, but is insufficient to open even round 1.

===Playing red 3s===
A common house rule requires that red 3s are played into a special pile, and immediately replaced ''when it is the player's turn''. This may occur before the draw when the player first plays from either their hand or foot, or when they draw a red 3. Red 3s played in this manner do not count toward opening criteria.

===Drawing cards===
Once a player has played any red 3s in their hand, they may choose (or be forced to) draw cards. This takes place in BGA by clicking on the draw pile, and delivers two cards into the hand.

===Taking the discard===
If the player is allowed by the house rules, they may pick up the top discard. Common house rules require the player to (1) have two cards of the same rank in their hand, and (2) be able to immediately play all three cards to the board. Among other things, this means that his team either (a) has already opened its board, or (b) the player taking the discard can meet the opening criteria for the round.

Once the player has taken and played the discard and associated meld cards, most rules require the taking of additional cards from the discard pile. This is generally six cards, or the entire pile if it is less, but there are house rules that require the pile to have at least six more cards in it, or that require the taking of the entire discard pile in the manner of traditional Canasta rules. A discard pile rich in black 3s can discourage the taking of discards.

===Playing cards===
Playing cards to the board consists of selecting a group of matching cards (all of the same rank with optional wild cards), and clicking on either the "New Meld" panel or the meld of the given rank on the team's meld board. If melds are limited in size, you will not be allowed to make a meld have more than seven cards.

You can have only one meld of a given rank open at any time. In order to create a meld, you must have at least three cards to play to it. You must always have more non-wild than wild cards in a meld, and common house rules limit the number of wild cards in a completed meld to either 2 or 3. The BGA version of the game enforces this by a "ratio rule", requiring a certain percentage of the cards in a meld at any given time to be non-wild.

You cannot play the last card from your foot unless your team has made the contracted melds. It is for this reason you can ''undo'' your moves.

===Discarding===
To discard, select a single card, and click on the discard pile. If it is the last card of your foot, you will not be allowed to discard it if your team does not have the contracted melds. In that case, you will have to undo your moves, and play so as to have at least one card remaining in your hand after discarding.

==Round and game summaries==
At the end of each round, a scoring summary is displayed, showing how each team made its points in the round. At the end of the game, the report includes all of the game rounds.