This is a documentation for Board Game Arena: play board games online !

Децк

Извор: Board Game Arena
Пређи на навигацију Пређи на претрагу

"Децк" ис оне оф тхе мост усефул цомпонент он ПХП сиде. Wитх "Децк", yоу цан манаге цардс оф yоур гаме он сервер сиде.

Усинг "децк", yоу wилл бе абле то усе тхе фоллоwинг феатурес wитхоут wритинг а сингле СQЛ датабасе реqуест:

  • Плаце цардс ин пиле, схуффле цардс, драw цардс оне бy оне ор манy бy манy.
  • "Ауто-ресхуффле" дисцард пиле инто децк wхен децк ис емптy.
  • Мове цардс бетwеен дифферент лоцатионс: хандс оф плаyерс, тхе табле, ...


Усинг Децк: Хеартс еxампле

Децк цомпонент ис массивелy усед ин "Хеартс" еxампле гаме - а цард гаме. Yоу цан финд ин "хеартс.гаме.пхп" тхат тхе објецт "$тхис->цардс" ис усед манy тимес.

Децк овервиеw

Wитх Децк цомпонент, yоу манаге алл цардс оф yоур гаме.

Тхе 5 пропертиес оф еацх цард

Усинг Децк цомпонент, еацх цард wилл хаве 5 пропертиес:

  • ид: Тхис ис тхе униqуе ИД оф еацх цард.
  • тyпе анд тyпе_арг: Тхесе тwо валуес дефинес тхе тyпе оф yоур цард (=wхат сорт оф цард тхис ис?).
  • лоцатион анд лоцатион_арг: Тхесе тwо валуес дефинес wхере ис тхе цард ат ноw.

ид, тyпе анд тyпе_арг пропертиес аре цонстантс дуринг тхе гаме. лоцатион анд лоцатион_арг аре цхангинг wхен yоур цардс аре мовинг фром плацес то плацес он тхе гаме ареа.

ид ис тхе униqуе ИД оф еацх цард. Тwо цардс цан'т гет тхе саме ИД. ИДс аре генератед аутоматицаллy бy тхе Децк цомпонент wхен yоу цреате цардс дуринг тхе Сетуп пхасе оф yоур гаме.

тyпе анд тyпе_арг дефинес тхе тyпе оф yоур цард. тyпе ис а схорт стринг, анд тyпе_арг ис ан интегер. Yоу цан усе тхесе тwо валуес ас yоу wант то маке суре yоу wилл бе абле то идентифy тхе дифферент цардс оф тхе гаме. Сее усаге оф "тyпе" анд "тyпе_арг" белоw.

Еxамплес оф усаге оф "тyпе" анд "тyпе_арг":

  • Ин "Хеартс", "тyпе" ис тхе цолор оф тхе цард (1 то 4) анд "тyпе_арг" ис тхе валуе оф тхе цард (1, 2, ... 10, Ј, Q, К).
  • Ин "Сеасонс", "тyпе" ис тхе тyпе оф тхе цард (еx: 1 ис Амулет оф Аир, 2 ис Амулет оф Фире, етц...). тyпе_арг ис нот усед.
  • Ин "Такеноко", а Децк цомпонент ис усед фор објецтиве цардс. "тyпе" ис тхе кинд оф објецтиве (ирригатион/панда/плот) анд "тyпе_арг" ис тхе ИД оф тхе специфиц објецтиве то реализе (еx: "а греен бамбоо x4"). Ноте тхат а сецонд Децк цомпонент ис усед ин Такеноко то манаге тхе "гарден плот" пиле.


лоцатион анд лоцатион_арг дефинес wхере ис тхе цард ат ноw. лоцатион ис а схорт стринг, анд лоцатион_арг ис ан интегер.

Yоу цан усе 'лоцатион' анд 'лоцатион_арг' ас yоу wант, то мове yоур цард он тхе гаме ареа. Алтхоугх, тхере аре 3 специал 'лоцатион' тхат Децк манаге специфицаллy. Yоу цан цхоосе то усе - ор нот то усе - тхесе лоцатионс депендинг оф yоур неедс:

  • 'децк': ин 'децк' лоцатион, цардс аре плацед фаце доwн ин а пиле анд аре драwн дуринг тхе гаме. 'лоцатион_арг' ис усед то специфy wхере тхе цард ис ин тхе децк пиле (тхе цард wитх тхе биггест лоцатион_арг ис тхе неxт то бе драwн).
  • 'ханд': ин 'ханд' лоцатион, цардс аре ин тхе ханд оф а плаyер. 'лоцатион_арг' ис сет то тхе ИД оф тхис плаyер.
  • 'дисцард': ин 'дисцард' лоцатион, цардс аре дисцардед, анд аре реадy то бе схуффлед инто тхе децк иф неедед (сее "ауторесхуффле").


Типс: усинг Децк цомпонент, yоу аре гоинг то усе генериц пропертиес ("лоцатион", "тyпе_арг",...) фор специфиц пурпосес оф yоур гаме. Тхус, дуринг тхе десигн степ бефоре реализинг yоур гаме, таке 2 минутес то wрите доwн wхат ис тхе меанинг оф еацх оф тхис генериц пропертиес ин тхе цонтеxт оф yоур гаме.

Цреате а неw Децк цомпонент

Фор еацх Децк цомпонент ин yоур гаме, yоу неед то цреате а дедицатед табле ин датабасе. Тхис табле хас а стандард формат. Ин працтицал, иф yоу wант то хаве а Децк цомпонент намед "цард", yоу јуст хаве то цопy/пасте тхе фоллоwинг ин yоур "дбмодел.сqл": 

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

Онце yоу дид тхис (анд рестарт yоур гаме), yоу цан децларе yоур Децк цомпонент ин yоур ПХП цоде ин yоур цласс цонструцтор. Фор Хеартс фор еxампле, I аддед то "Хеартс()" метход: 

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

Ноте тхат wе специфy "цард" хере, тхе наме оф оур превиоуслy цреатед табле. Ит меанс yоу цан цреате северал "Децк" wитх северал таблес. Мост оф тхе тиме тхис ис унусефул: а Децк цомпонент схоулд манаге алл објецтс оф тхе саме кинд (еx: алл цардс оф тхе гаме).

Афтерwардс, wе цан инитиализе yоур "Децк" бy цреатинг алл тхе цардс оф тхе гаме. Генераллy, тхис ис доне онлy онце дуринг тхе гаме, дуринг тхе "сетупНеwГаме" метход.

"Децк" цомпонент провидес yоу а фаст wаy то инитиализе алл yоур цардс ат онце: цреатеЦардс. Хере ис хоw ит ис усед фор "Хеартс": 

        // Create cards
        $cards = array();
        foreach( $this->colors as  $color_id => $color ) // spade, heart, diamond, club
        {
            for( $value=2; $value<=14; $value++ )   //  2, 3, 4, ... K, A
            {
                $cards[] = array( 'type' => $color_id, 'type_arg' => $value, 'nbr' => 1);
            }
        }

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

Ас yоу цан сее, "цреатеЦардс" такес а десцриптион оф алл цардс оф тхе гаме. Фор еацх тyпе оф цард, yоу хаве то специфy итс "тyпе", "тyпе_арг" анд тхе нумбер оф цард то цреате. "цреатеЦардс" цреате алл цардс анд плаце тхем инто тхе "децк" лоцатион (ас специфиед ин тхе сецонд аргумент).

Ноw, yоу аре реадy то усе "Децк"!

Симпле еxамплес усинг Децк

(Мост еxамплес аре фром "Хеартс" гаме) 

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

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

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

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



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

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

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

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

Децк цомпонент референце

Инитиализинг Децк цомпонент

инит( $табле_наме )

Инитиализе тхе Децк цомпонент.

Аргумент:

  • табле_наме: наме оф тхе ДБ табле усед бy тхис Децк цомпонент.

Муст бе цаллед бефоре анy отхер Децк метход.

Усуаллy, инит ис цаллед ин yоур гаме цонструцтор.

Еxампле wитх Хеартс: 

	function Hearts( )
	{
        (...)
        
        $this->cards = self::getNew( "module.common.deck" );
        $this->cards->init( "card" );
	}

цреатеЦардс( $цардс, $лоцатион='децк', $лоцатион_арг=нулл )

Цреате цард итемс ин yоур децк цомпонент. Усуаллy, алл цард итемс аре цреатед онце, дуринг тхе сетуп пхасе оф тхе гаме.

"цардс" десцрибе алл цардс тхат неед то бе цреатед. "цардс" ис ан арраy wитх тхе фоллоwинг формат: 

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

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

Ноте: Дуринг тхе "цреатеЦардс" процесс, Децк генерате униqуе ИДс фор алл цард итемс.

Ноте: цреатеЦардс ис оптимизед то цреате а лот оф цардс ат онце. До нот усе ит то цреате цардс оне бy оне.

Иф "лоцатион" анд "лоцатион_арг" аргументс аре нот сет, неwлy цреатед цардс аре плацед ин тхе "децк" лоцатион. Иф "лоцатион" (анд оптионаллy лоцатион_арг) ис специфиед, цардс аре цреатед фор тхис специфиц лоцатион.

Цард стандард формат

Wхен Децк цомпонент метходс аре ретурнинг оне ор северал цардс, тхе фоллоwинг формат ис усед: 

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

=== Picking cards ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=== Moving cards ===

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

Move the specific card to given location.

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


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

Move the specific cards to given location.

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

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

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

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

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

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

Move a card on top or at bottom of given "pile" type location.

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

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

_ from_location: where to take the cards
_ to_location: where to put the cards
_ from_location (optional): if specified, only cards with given "location_arg" are moved.
_ to_location (optional): if specified, cards moved "location_arg" is set to given value. Otherwise location_arg is set to zero.

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

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

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

'''playCard( $card_id )'''

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

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

=== Get cards informations ===

'''getCard( $card_id )'''

Get specific card information.

Return null if this card is not found.

'''getCards( $cards_array )'''

Get specific cards information.

cards_array is an array of cards ID.

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

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

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

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

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

Return the number of cards in specified location.

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

'''countCardsInLocations()'''

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

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

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

цоунтЦардсБyЛоцатионАргс( $лоцатион )

Ретурн тхе нумбер оф цардс ин еацх "лоцатион_арг" фор тхе гивен лоцатион.

Тхе метход ретурнс ан ассоциативе арраy wитх тхе формат "лоцатион_арг" => "нумбер оф цардс".

Еxампле: цоунт тхе нумбер оф цардс ин еацх плаyер'с ханд: 

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


гетПлаyерХанд( $плаyер_ид )

Гет алл цардс ин гивен плаyер ханд.

Ноте: Тхис ис ан алиас фор: гетЦардсИнЛоцатион( "ханд", $плаyер_ид )

гетЦардОнТоп( $лоцатион )

Гет тхе цард он топ оф тхе гивен ("пиле" стyле) лоцатион, ор нулл иф тхе лоцатион ис емптy.

Ноте тхат тхе цард пиле wон'т бе "ауто-ресхуффлед" иф тхере ис но море цард аваилабле.

гетЦардсОнТоп( $нбр, $лоцатион )

Гет тхе "$нбр" цардс он топ оф тхе гивен ("пиле" стyле) лоцатион.

Тхе метход ретурн ан арраy wитх ат мост "$нбр" елементс (ор а воид арраy иф тхере ис но цард ин тхис лоцатион).

Ноте тхат тхе цард пиле wон'т бе "ауто-ресхуффлед" иф тхере ис нот еноугх цардс аваилабле.

гетЕxтремеПоситион( $бГетМаx ,$лоцатион )

(рарелy усед)

Гет тхе поситион оф цардс ат тхе топ оф тхе гивен лоцатион / ат тхе боттом оф тхе гивен лоцатион.

Оф цоурсе тхис метход wоркс онлy он лоцатион ин "пиле" wхере yоу аре усинг "лоцатион_арг" то специфy тхе поситион оф еацх цард (еxампле: "децк" лоцатион).

Иф бГетМаx=труе, ретурн тхе лоцатион оф тхе топ цард оф тхе пиле.

Иф бГетМаx=фалсе, ретурн тхе лоцатион оф тхе боттом цард оф тхе пиле.

гетЦардсОфТyпе( $тyпе, $тyпе_арг=нулл )

Гет алл цардс оф а специфиц тyпе (рарелy усед).

Ретурн ан арраy оф цардс, ор ан емптy арраy иф тхере ис но цардс оф тхе специфиед тyпе.

_ тyпе: тхе тyпе оф цардс _ тyпе_арг: иф специфиед, ретурн онлy цардс wитх тхе специфиед "тyпе_арг".

Схуффлинг

схуффле( $лоцатион )

Схуффле алл цардс ин специфиц лоцатион.

Схуффле онлy wоркс он лоцатионс wхере цардс аре он а "пиле" (еx: "децк").

Плеасе ноте тхат алл "лоцатион_арг" wилл бе ресетед то рефлецт тхе неw ордер оф тхе цардс ин тхе пиле.

Преузето из „http:///index.php?title=Deck&oldid=650”