Documentation

Deck

The BGA Studio Deck component

Using the deck component, 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.

The deck contains cards which have the following structure:

[
   'id' => 50,           // The id of the card, generated by the Deck component
   'type' => 2,          // A string representing the card type, e.g. suits may be represented
                         // by the numbers 1 through 4
   'type_arg' => ..,     // An integer representing the card type argument, e.g. the value of
                         // the card may be represented by the numbers 1 through 13 for Ace through to King
   'location' => 'deck', // A string representing a location, or pile, of cards
   'location_arg' => 3   // An integer represeting a sub-location in the location. This can be used for the card
                         // position, e.g. in a deck, or for splitting a location, e.g. creating a hand per
                         // player in the 'hand' location
];

Auto-reshuffling:

To enable auto-reshuffle you must set $deck->autoreshuffle to true during the setup of the component.

With auto-reshuffle enabled, if the deck location is empty when you try to retrieve a card from it, the discard location will automatically be reshuffled into the deck location.

If you need to notify players when the deck is shuffled, you can assign a callback method to $cards->autoreshuffle_trigger, e.g. $cards->autoreshuffle_trigger = [$this, 'deckAutoReshuffle'];.

You can override the locations that auto-reshuffle uses by setting $cards->autoreshuffle_custom, e.g. $cards->autoreshuffle_custom = ['deck' => 'discard'];, replacing 'deck' and 'discard' with your custom locations.

Table of Contents

init() Initialize the Deck component. mixed
createCards() Create card items in your deck component. mixed
pickCard() Pick a card from a location/pile (ex: 'deck') and place it in the 'hand' of specified player. array|null
pickCards() Return an array with the cards picked array|null
pickCardForLocation() Pick a card for any location. array|null
pickCardsForLocation() Pick cards for any location. array|null
moveCard() Move the specific card to given location. mixed
moveCards() Move the specific cards to given location. mixed
insertCard() Move a card to a specific "pile" location at a given position specified by `$location_arg`. mixed
insertCardOnExtremePosition() Move a card onto the top or bottom of a pile mixed
moveAllCardsInLocation() Move all cards from one location to another mixed
moveAllCardsInLocationKeepOrder() Move all cards from one location to another, maintaining their order mixed
playCard() Play the specified card, moving it to the discard pile mixed
getCard() Get an array containing the information about a specific card array|null
getCards() Get an array of card detail arrays for the specified card ids array
getCardsInLocation() Get all cards in specific location array
countCardInLocation() Count how many cards are in the specified location int
countCardsInLocations() Return the number of cards in each location of the game. array
countCardsByLocationArgs() Return the number of cards in each "location_arg" for the given location. array
getPlayerHand() Get all cards in the specified player's hand. array
getCardOnTop() Get the top card from a location array|null
getCardsOnTop() Return the specified number of cards from a location/pile array
getExtremePosition() Gets the position of a card at the top or bottom of the given location mixed
getCardsOfType() Get all cards of a specific type array
getCardsOfTypeInLocation() Get all of a type of card from a location array
shuffle() Shuffle the cards in a location mixed

Methods

init()

Initialize the Deck component.

public init( $table_name : string ) : mixed

Usually, init is called in your game constructor. Must be called before any other Deck method.

Example usage:

$this->cards = self::getNew( "module.common.deck" );
$this->cards->init( "card" );
Parameters
$table_name : string

Name of the DB table used by this Deck component

Return values
mixed

createCards()

Create card items in your deck component.

public createCards( $cards : array [, $location : string = 'deck' ] [, $location_arg : int = null ] ) : mixed

Usually, all card items are created once, during the setup phase of the game. During the createCards process, Deck generates unique IDs for all card items.

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

By default, 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.

Parameters
$cards : array

An array describing all cards that need to be created: $cards = [ [ 'type' => 1, 'type_arg' => 99, 'nbr' => 1 ], [ 'type' => 2, 'type_arg' => 12, 'nbr' => 4 ], ... ];

$location : string = 'deck'

The location to create cards in. By default this will be the deck.

$location_arg : int = null

The position in the pile to insert the card at. If not specified $location_arg will be set to 0, indicating the top of the pile.

Return values
mixed

pickCard()

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

public pickCard( $location : string , $player_id : ) : array|null

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

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

Parameters
$location : string
$player_id :
Return values
array|null

pickCards()

Return an array with the cards picked

public pickCards( $nbr : int , $location : string , $player_id : ) : array|null

Returns up to a maximum of $nbr, or null if there are no more cards in given 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.

Parameters
$nbr : int

The number of cards to return. If there are not enough cards in the location, less cards may be returned.

$location : string

The location to pick cards from.

$player_id :
Return values
array|null

pickCardForLocation()

Pick a card for any location.

public pickCardForLocation( $from_location : string , $to_location : string , $location_arg : int ) : array|null

Similar to pickCard, but not limited to hand locations.

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

Parameters
$from_location : string

The "pile" style location from where you are picking a card.

$to_location : string

The location where you will place the card picked.

$location_arg : int

The position in the pile to insert the card at. If not specified $location_arg will be set to 0, indicating the top of the pile.

Return values
array|null

pickCardsForLocation()

Pick cards for any location.

public pickCardsForLocation( $nbr : int , $from_location : string , $to_location : string , $location_arg : int [, $no_deck_reform : bool = false ] ) : array|null

Similar to pickCards, but not limited to hand locations.

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

Parameters
$nbr : int

The number of cards to return. If there are not enough cards in the location, less cards may be returned.

$from_location : string

The "pile" style location from where you are picking a card.

$to_location : string

The location where you will place the card picked.

$location_arg : int

The position in the pile to insert the card at. If not specified $location_arg will be set to 0, indicating the top of the pile.

$no_deck_reform : bool = false

If set to "true", the auto-reshuffle feature is disabled during this method call.

Return values
array|null

moveCard()

Move the specific card to given location.

public moveCard( $card_id : int , $location : string , $location_arg : int ) : mixed
Parameters
$card_id : int

ID of the card to move.

$location : string

Location to move the card to.

$location_arg : int

The position in the pile to insert the card at. If not specified $location_arg will be set to 0, indicating the top of the pile.

Return values
mixed

moveCards()

Move the specific cards to given location.

public moveCards( $cards : array , $location : string , $location_arg : int ) : mixed
Parameters
$cards : array

An array of IDs of cards to move.

$location : string

Location to move the card to.

$location_arg : int

The position in the pile to insert the card at. If not specified $location_arg will be set to 0, indicating the top of the pile.

Return values
mixed

insertCard()

Move a card to a specific "pile" location at a given position specified by `$location_arg`.

public insertCard( $card_id : int , $location : string , $location_arg : int ) : mixed

If there is already a card in the position specified by $location_arg, increment all cards after $location_arg in order to insert new card at this position.

To specifically place a card on the top or bottom of a pile, use insertCardOnExtremePosition instead.

Parameters
$card_id : int

ID of the card to move.

$location : string

Location to insert the card into.

$location_arg : int

The position in the pile to insert the card at.

Return values
mixed

insertCardOnExtremePosition()

Move a card onto the top or bottom of a pile

public insertCardOnExtremePosition( $card_id : int , $location : string , $bOnTop : bool ) : mixed
Parameters
$card_id : int

The id of the card to move

$location : string

The location to move the card to

$bOnTop : bool
Return values
mixed

moveAllCardsInLocation()

Move all cards from one location to another

public moveAllCardsInLocation( $from_location : string , $to_location : string [, $from_location_arg : int|null = null ] , $to_location_arg : int ) : mixed

If you want to move the cards and keep their current order, you should use moveAllCardsInLocationKeepOrder()

Parameters
$from_location : string

Where to move the cards from

$to_location : string

Where to move the cards to

$from_location_arg : int|null = null

If specified, only cards at the position given by $from_location_arg are moved

$to_location_arg : int

If specified, the moved cards are added to the location at this position. Otherwise the cards are moved to the top of the $to_location

Return values
mixed

moveAllCardsInLocationKeepOrder()

Move all cards from one location to another, maintaining their order

public moveAllCardsInLocationKeepOrder( $from_location : string , $to_location : string ) : mixed
Parameters
$from_location : string
$to_location : string
Return values
mixed

playCard()

Play the specified card, moving it to the discard pile

public playCard( $card_id : int ) : mixed

This is a helper method for insertCardOnExtremePosition($card_id, "discard", true)

Parameters
$card_id : int
Return values
mixed

getCard()

Get an array containing the information about a specific card

public getCard( $card_id : int ) : array|null

Returns null if the card isn't found

Parameters
$card_id : int
Return values
array|null

getCards()

Get an array of card detail arrays for the specified card ids

public getCards( $cards_array : array ) : array
Parameters
$cards_array : array
Tags
throws

Throws an Unexpected exception if either:

  • Not all the cards are found, or
  • Card ids are specified multiple times
Return values
array

getCardsInLocation()

Get all cards in specific location

public getCardsInLocation( $location : string [, $location_arg : int|null = null ] [, $order_by : string|null = null ] ) : array

Returns an array of card detail arrays for the specified location

Parameters
$location : string

The location to get the cards for

$location_arg : int|null = null

If specified, only the cards at this position will be returned

$order_by : string|null = null

If specified, the cards will be returned ordered by this database field

Return values
array

countCardInLocation()

Count how many cards are in the specified location

public countCardInLocation( $location : string [, $location_arg : int|null = null ] ) : int
Parameters
$location : string

The location you want to count the cards in

$location_arg : int|null = null

If specified, only the cards at this position will be counted

Return values
int

countCardsInLocations()

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

public countCardsInLocations( ) : array

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

Example return:

[
    'deck' => 12,
    'hand' => 21,
    'discard' => 54,
    'ontable' => 3
];
Return values
array

countCardsByLocationArgs()

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

public countCardsByLocationArgs( $location : string ) : array

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:

$this->countCardsByLocationArgs('hand');
// Result:
[
    122345 => 5,    // player 122345 has 5 cards in hand
    123456 => 4     // and player 123456 has 4 cards in hand
];
Parameters
$location : string
Return values
array

getCardOnTop()

Get the top card from a location

public getCardOnTop( $location : string ) : array|null

Returns an array containing the card information, or null if the location is empty. This method will not cause the location to be auto-reshuffled if there are no more cards in the location.

Parameters
$location : string
Return values
array|null

getCardsOnTop()

Return the specified number of cards from a location/pile

public getCardsOnTop( $nbr : int , $location : string ) : array

This method will not cause the location to be auto-reshuffled if there are no more cards in the location.

Parameters
$nbr : int
$location : string
Return values
array —

An array with at most $nbr elements, or an empty array if there are no cards in this location

getExtremePosition()

Gets the position of a card at the top or bottom of the given location

public getExtremePosition( $bGetMax : bool , $location : string ) : mixed

This method works only on a "pile" location, i.e. where you are using location_arg to specify the position of each card (ex: deck location).

Parameters
$bGetMax : bool

true to return the location of the top card, false for the bottom card

$location : string
Return values
mixed

getCardsOfType()

Get all cards of a specific type

public getCardsOfType( $type : string [, $type_arg : int|null = null ] ) : array
Parameters
$type : string

The type of the cards to return

$type_arg : int|null = null

If specified, only return cards of this $type_arg

Return values
array —

An array of card details, or an empty array if no cards of the type were found

getCardsOfTypeInLocation()

Get all of a type of card from a location

public getCardsOfTypeInLocation( $type : string [, $type_arg : int|null = null ] , $location : string [, $location_arg : string|null = null ] ) : array
Parameters
$type : string

The type of the cards to return

$type_arg : int|null = null

If specified, only return cards of this $type_arg

$location : string
$location_arg : string|null = null
Return values
array —

An array of card details, or an empty array if no cards of the type were found

shuffle()

Shuffle the cards in a location

public shuffle( $location : string ) : mixed

Shuffle only works on locations where cards are on a "pile" (ex: deck). After calling shuffle, $location_arg will be updated for all of the cards in the location.

Parameters
$location : string
Return values
mixed

Search results