Games::Euchre::AI - Player API for Euchre card game
This class implements a skeletal Euchre player programming interface. Subclasses can be created quite easily as interactive interfaces or AI computer players.
If you wish to write your own computer player, I recommend you start with Games::Euchre::AI::Simple. If you wish to write your own human interface, I recommend you start with Games::Euchre::AI::Human.
Create and initialize a new Euchre AI. This object is implemented as an empty hash. Subclasses may wish to use this hash for state storage.
The following methods are called in the course of the game where the AI (or human) has to make a decision. The state of the game is always passed in a hashreference. The following fields are always available:
'name' is the name of the current player. This is useful for output messages.
'names' is a hash relating player number to player name for all four players.
'debug' is a boolean indicating if we are debugging game or the AIs. Your AI may wish to provide verbose output if debugging is going on.
Choose trump or pass. The relevent details of the current state of the game are provided in a hash reference. Here is an example of that data structure:
{ name => 'Player 1', names => {1 => 'Player 1', 2 => 'P2', 3 => 'P3', 4 => 'Fred'}, number => 1, turnedUp => 'KH', passes => 1, ourScore => 2, theirScore => 4, winScore => 10, hangdealer => false, notrump => false, hand => ['JS', 'QH', '9S', 'KC', 'AD'], debug => false, }
'turnedUp' is the suit and value of the card on the top of the blind. This will be undef on the second round of bidding.
'passes' says how many people have passed so far
'hangdealer' is a boolean saying whether the 'hang-the-dealer' optional rule is in effect
'notrump' is a boolean saying whether the 'no trump' optional rule is in effect
This function must return one of: H, D, C, S, N, HA, DA, CA, SA, NA, or undef
'N' means 'no trump', 'A' means 'alone', undef means 'pass'. Not all of these are legal at any given round! Use the isLegalBid() method below if you are unsure.
If this is called, you are the dealer and someone called trump. Choose which card from your hand to discard in exchange for the top card of the blind. The relevent details of the current state of the game are provided in a hash reference. Here is an example of that data structure:
{ name => 'Player 1', names => {1 => 'Player 1', 2 => 'P2', 3 => 'P3', 4 => 'Fred'}, number => 1, turnedUp => 'KH', trump => 'H', bidder => 2, weBid => false, usAlone => false, themAlone => false, hand => ['JS', 'QH', '9S', 'KC', 'AD'], debug => false, }
This method should return the 0-based index of the card to trade for the turnedUp card. Namely, this in the index of the 'hand' array for the card that you choose.
Choose which card from your hand to play on this trick. The relevent details of the current state of the game are provided in a hash reference. Here is an example of that data structure:
{ name => 'Player 1', names => {1 => 'Player 1', 2 => 'P2', 3 => 'P3', 4 => 'Fred'}, number => 1, trump => 'H', bidder => 2, weBid => true, usAlone => false, themAlone => false, trick => 2, ourTricks => 0, theirTricks => 1, ourScore => 2, theirScore => 4, winScore => 10, played => ['10H', '9H', 'QC'], playedBy => [2, 3, 4, 1], hand => ['JH', 'AH', 'AS', 'KS'], debug => false, }
'playedBy' is an arrayref of numbers of the players in the order they will play. Without this, the alone possibility makes it hard to tell who played what.
Any needed information not stored here (like who was the dealer, what was the turn-up card, what happened in the first trick) is YOUR responsibility to collect and store in your instance.
This method should return the 0-based index of the card to play. Namely, this in the index of the 'hand' array for the card that you choose.
These methods are called when certain events happen in the game. They are for informational purposes only, and no values should be returned. Unlike the methods above, these really only need to be overridden for human players, or debugging output, or ubersmart robots.
{ name => 'Player 1', names => {1 => 'Player 1', 2 => 'P2', 3 => 'P3', 4 => 'Fred'}, number => 1, trump => 'H', dealer => 1, bidder => 2, weBid => false, usAlone => false, themAlone => false, debug => false, }
'trump' may be undef if everybody passed (which means a new turn is about to start).
{ name => 'Player 1', names => {1 => 'Player 1', 2 => 'P2', 3 => 'P3', 4 => 'Fred'}, number => 1, played => ['KH', '9H', 'JC', '9S'], playedBy => [2, 3, 4, 1], myCard => 3, winCard => 0, winner => 2, debug => false, }
'myCard' is 0-based index in the 'played' array for the card played by this player. It is undef if the player's teammate went alone.
'winCard' is the 0-based index of the winning card. The mapping of winning card index to winning player number may not be obvious due to the possibility of players going alone, so both numbers are explicitly provided.
'winner' is the 1-based number of the winning player.
{ name => 'Player 1', names => {1 => 'Player 1', 2 => 'P2', 3 => 'P3', 4 => 'Fred'}, number => 1, ourTricks => 3, theirTricks => 2, winType => 'win', ourScore => 8, theirScore => 6, winScore => 10, debug => false, }
'winType' is one of: 'win', 'all', 'alone', 'euchre', which is 1, 2, 4, and 2 points respectively.
{ name => 'Player 1', names => {1 => 'Player 1', 2 => 'P2', 3 => 'P3', 4 => 'Fred'}, number => 1, ourScore => 10, theirScore => 6, debug => false, }
These methods are used to specify the programmatic behavior of your AI across mutliple games. Many AIs won't need this.
This method should return a boolean indicating whether the AI wants to live longer than one game. When a new game starts, this method is called. If it returns true, the instance is retained and the reset() method is called. If it returns false, the game will just call new() again creating a new instance. The default is falsee. If you override this to return true, you should override the reset() method too.
Called to refresh the instance between games.
These are routines of general convenience. They are never called from external objects. They can be called as class methods or instance methods.
Given a state hash and bid of the form described in the bid() method above, return a boolean indicating whether that bid is valid.
Given a state hash and a hand index of the form described in the playCard() method above, return a boolean indicating whether that choice of plays is valid.
Given a state hash from either any of the above action methods [e.g. bid(), pickItUp() or playCard()], return the suit of a card, properly accounting for suit of the left jack if trump has been called. The card argument should be in the form of '10C' or 'KD'. The return value will be one of 'H', 'C', 'S' or 'D'.
Games::Euchre
GNU Public License, version 2
Chris Dolan, chrisdolan@users.sourceforge.net
To install Games::Euchre, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Games::Euchre
CPAN shell
perl -MCPAN -e shell install Games::Euchre
For more information on module installation, please visit the detailed CPAN module installation guide.