Description: A deck of cards with fully implemented individual cards; when the player has a full poker hand, the inventory listing describes the resulting hand accordingly.
In our previous implementations of playing cards, we've gotten as far as creating decks of individual cards that the player can draw and discard. But in a poker game, one doesn't just have a collection of cards: one has a hand of a specific kind.
Here we take on the job of writing an inventory listing for a poker hand that will reflect the real value of what the player has drawn. To do this, we create a rulebook to sort and assess the cards in the player's hand; its possible return values are limited to the kinds of poker hands that exist, from "high card" to "royal flush".
The first three sections, creating the deck of cards and the means to parse their names, are identical to those we've already seen in Tilt 1; new material begins at section 4.
For the purposes of demonstration, we're simulating something akin to five-card draw without wilds; stud or hold-em variations would add some other complexities.
Suit is a kind of value. The suits are hearts, clubs, diamonds, and spades. Understand "heart" as hearts. Understand "club" as clubs. Understand "diamond" as diamonds. Understand "spade" as spades.
A card is a kind of thing. A card has a suit. A card has a number called rank. Understand the suit property as describing a card. Understand the rank property as describing a card.
now current suit is the suit after the current suit.
Section 2 - The Deck and the Discard Pile
The Empty Room is a room. "Nothing to see here."
The deck of cards is in the Empty Room. It is a closed unopenable container. The description is "A standard poker deck."
The discard pile is a closed unopenable container. The description is "Cards in this game are discarded face-down, so the discard pile is not very interesting to see. All you can observe is that it currently contains [if the number of cards which are in the discard pile is less than ten][the number of cards which are in the discard pile in words][otherwise]about [the rounded number of cards which are in the discard pile in words][end if] card[s]."
To decide what number is the rounded number of (described set - a description of objects):
let N be the number of members of the described set;
Understand the commands "take" and "carry" and "hold" and "get" and "drop" and "throw" and "discard" as something new.
Understand "take [text]" or "get [text]" or "drop [text]" as a mistake ("Here, you only draw and discard. Nothing else matters at the moment.").
Understand "draw" or "draw card" or "draw a card" as drawing. Drawing is an action applying to nothing. The drawing action has an object called the card drawn.
Setting action variables for drawing:
now the card drawn is a random card which is in the deck of cards.
The ranking of poker hands traditionally depends on three features: 1) whether all the cards are of the same suit (flush); 2) whether the cards constitute a numerical run of ranks (straight); and 3) how many cards or sets of cards are of matching rank (pairs, three of a kind, and four of a kind). Here we will start by assessing our hand to determine these qualities:
{**}The hand-ranking rules is a rulebook. The hand-ranking rules have outcomes royal flush, straight flush, four of a kind, full house, flush, straight, three of a kind, two pairs, pair, high card.
For convenience in identifying hand features, and for elegance when we print the hand-listing, we start by sorting the cards in the player's hand so that the high-ranked cards are listed first. It is rare that we want to concern ourselves with this, but as we saw in the section on "Looking at containment by hand" in the chapter on Change, Inform keeps an ordered list of the items inside any given container; so it does order the objects in the player's hand, and the ordering depends on which things were added to the hand most recently. By moving something to the player's hand again (even if it was already there), we change this ordering, and wind up with a sorted hand.
{**}A card can be sorted or unsorted. A card is usually unsorted.
This last printing instruction is there for diagnostic purposes: later we'll add a testing command to turn debugging on and off; when it's on, the game will print out its card list at various stages in sorting, to help us trouble-shoot any problems. In normal play, however, this will be off.
Next up, a check to see whether the player has a flush:
{**}A hand-ranking rule (this is the finding flushness rule):
let called suit be the suit of a random card carried by the player;
if every card carried by the player is called suit, now flushness is true.
Now we check for straights; this is slightly complicated by the fact that an ace can be either the bottom of a low straight (lower than 2) or the top of a high straight (higher than king), so we explicitly check both possibilities.
let N be the rank of the highest card which is carried by the player;
repeat with current rank running from N - 4 to N:
now the test rank is the current rank;
unless the player carries a matching card:
if the current rank is N - 4 and the current rank is 9 and the player carries an ace card, do nothing; [this covers the case where an ace could be the top card of the sequence]
And finally, we need to identify any groups of cards of the same rank. We want to know how many groups there are and how large each group is (though in practice there can only be one group of three or four in a standard-sized poker hand). We also want to mark any grouped cards so that we can move them to the front of the player's hand when we take inventory.
Next we tweak our sorting to reflect the make-up of the hand. There are two reasons why this might differ from the straight highest-to-lowest sort we did earlier:
1) we want to list aces as high unless they are serving as the bottom of a low straight, in which case they should appear last;
2) we want combinations to appear at the front of the list, sorted from highest value to lowest value: larger combinations first, then smaller combinations, and combinations of equal size sorted by rank.
{**}A hand-ranking rule (this is the move aces up unless there's a low straight rule):
if sort-debugging is true, say "-- after ace movement rule: [list hand]".
A hand-ranking rule (this is the move pairs forward rule):
while the player carries a paired card:
let selection be the lowest paired card which is carried by the player;
move the selection to the player;
now the selection is uncombined;
if sort-debugging is true, say "-- after pairs movement: [list hand]".
A hand-ranking rule (this is the raise ace pairs rule):
if the player carries exactly two ace cards:
repeat with item running through ace cards which are carried by the player:
move item to the player;
if sort-debugging is true, say "-- after paired-ace movement: [list hand]".
A hand-ranking rule (this is the move multiples forward rule):
while the player carries a tripled card:
let selection be the lowest tripled card which is carried by the player;
move the selection to the player;
now the selection is uncombined;
while the player carries a quadrupled card:
let selection be the lowest quadrupled card which is carried by the player;
move the selection to the player;
now the selection is uncombined;
if sort-debugging is true, say "-- after multiples movement rule: [list hand]".
Definition: a card is ace if its rank is 1.
Definition: a card is king if its rank is 13.
Now, having determined the salient qualities of our hand, we run through rules in order from the highest kind of poker combination to the lowest. Because of the order of the source, Inform will choose whichever combination applies first.
{**}A hand-ranking rule (this is the royal-flush rule):
if flushness is true and straightness is true and the highest card carried by the player is king and the lowest card carried by the player is ace, royal flush.
A hand-ranking rule (this is the straight-flushes rule):
if flushness is true and straightness is true, straight flush.
And finally, we need to define our debugging variable here, even though we won't give the player the ability to turn it on and off except in the special testing section.
For many examples, a test-me script is enough to prove that the example does what it ought. This example, though, is a bit more complicated, and hard to test randomly. The remainder of the source here shows how we might write a test to verify the desired behavior of our rulebook. Those who are only interested in the rulebook itself can stop reading at this point.
{**}Section 5 - Testing hand identification - Not for release
For the sake of testing our rules, we provide an apparatus that will load the player's hand up with sample hands of each kind, then show the result to make sure that the hand is being correctly identified.
The somewhat rough-and-ready principle of this table is that we will overwrite the cards in the player's hand by resetting their ranks and suits; every five rows of the table represent a new poker hand for the game to attempt to sort and identify. These include one example of each of the major kinds of poker hand, plus a couple of variations involving aces which test the special sorting rules.