Author image Jeff Till
and 1 contributors

NAME

Games::Hanabi - rules engine for the 'hanabi' card game

VERSION

version 0.001

DESCRIPTION

Hanabi is a card game in which players take turns playing cards in 5 suits, sequentially from 1 to 5. The catch is that players can only see each others' hands, and not their own. They must give hints to each in order to succceed.

This distribution implements the rules for the game (no variations).

Games::Hanabi itself tracks everything needed for a game of Hanabi.

To see an example of this module in use, look at the attached script bin/hanabi_ai.pl

METHODS

Constructor

  • my $game = Games::Hanabi->new(players=>2, derive=>1, debug=>0);

    Create a new hanabi game. All params are optional.

    • players: the number of players in the game. Starting player is random. (default 2)

    • derive: tell the game to deduce information about cards in players' hands. For example, if a player knows a card is not 1, 2, 3, or 4, it must be a 5. (default true) This greatly slows down turn processing.

    • debug: Print some addition debug messages during a game. (default false)

Game State

The game state is represented by a deep data structure described below. If is accessed via

  my $game_state = $game->get_game_state();

A game state is a hash with the following keys:

  • players

    The number of players in the game.

  • turn

    The current player. 0-index so 0 is player 1, 1 is player 2, etc.

  • score

    The score that the players have earned so far.

  • hints

    The number of hints remaining.

  • bombs

    The number of times the players have made invalid plays, earning a bomb.

  • countdown

    The number of turns remaining before the game ends. Before the deck is empty, this is undefined. Afterwards, it is set to the number of players, and decremented on each player's turn.

  • top_card

    A hash with keys of B, G, R, W, and Y (the card colors). The values of each is the highest card legally played in that color.

  • hands

    An array of hands, with 1 entry per player. Each player's hand is an array of cards. A card is a hashref with the following keys:

    • color

      The color of the card. One of B, G, R, W, or Y.

    • number

      The number of the card. One of 1, 2, 3, 4, or 5.

    • color_score

      A score representing how much information is known about the card's color. 10 points for positive information (i.e. the card is blue), or 1 point for each piece of negative information (i.e. the card is not blue).

    • number_score

      A score representing how much information is known about the card's number. 10 points for positive information (i.e. the card is a 3), or 1 point for each piece of negative information (i.e. the card is a 3).

    • score

      A score representing how much information is known about the card. score = color_score + number_score.

    • known_information

      A hashref with keys color and number representing what the holder of the card knows about this card.

      • color

        A hashref with keys of B, G, R, W, and Y. Each value is one of: 0 - the card is not that color 1 - the card is that color undef - Unknown either way

      • number

        A hashref with keys of 1, 2, 3, 4, and 5. Each value is one of: 0 - the card is not that number 1 - the card is that number undef - Unknown either way

  • deck

    An arrayref of cards representing the deck.

  • discards

    An arrayref of cards that have been discarded.

A card hash may have addition information used for internal record-keeping, but it is not reliable.

Public methods

  • $game->get_valid_moves()

    Return an array of moves that are valid for the current player. If the games is over, there are no valid moves, so return undef. The moves will have one of the following forms:

    • { action => 'play', index => 3 }

      Play the card with index 3 (i.e. the 4th card) from your hand.

    • { action => 'discard', index => 3 }

      Discard the card with index 3 (i.e. the 4th card) from your hand.

    • { action => 'hint', hint => 'G', player => 1 }

      Tell the player with index 1 (i.e. player 2) which cards in their hand are Green.

  • $game->take_action($action)

    Perform a valid game action. $action is of the form returned by get_valid_moves() Once the action is taken, move on to the next player's turn.

  • $game->is_valid_play($card)

    Boolean. Return whether the card can be played without triggering a bomb.

  • $game->is_valid_known_play($card)

    Boolean. Return whether the card can be played without triggering a bomb, using only the information the holder of the card knows about it. When unknown, return false.

  • $game->is_junk($card, $known)

    Boolean. Return whether the card is obsolete for this game, from the perspective of the holder of the card. If $known is true, then use perfect information instead.

  • max_score_for_color($color)

    Return the highest score a color can still earn (1-5). For example, if all of he Green 3's are discarded, the highest max score for Green is 2.

  • is_card_known($card)

    Boolean. Return whether the card's number AND color are known by the holding player.

  • is_number_known($card)

    Boolean. Return whether the card's number is known by the holding player.

  • is_card_known($card)

    Boolean. Return whether the card's color is known by the holding player.

  • print_game_state()

    Print a basic representation of the game state to the screen.

BUGS

Please report any bugs or feature requests to bug-games-hanabi at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Games-Hanabi. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

ACKNOWLEDGEMENTS

I definitely recommend you to buy a hanabi card game and play with friends, you'll have an exciting time.

SEE ALSO

You can find more information on the hanabi game on wikipedia at http://en.wikipedia.org/wiki/Hanabi.

You can find more information on this module at:

AUTHOR

Jeff Till

COPYRIGHT AND LICENSE

This software is Copyright (c) 2014 by Jeff Till.

This is free software, licensed under:

  The GNU General Public License, Version 3, June 2007