Chapter 18: Rulebooks
18.12. Outcome values

We have now seen two ways to write the outcome of a rule: as simple success or failure, with more or less explicit phrases like:

rule succeeds;
rule fails;
continue the action;
stop the action;

and by using a named outcome for the current rulebook as if it were a phrase, as in:

low background noise;

There is still a third way: we can stop a rule and at the same time supply a value. This means that rulebooks can be used to calculate quantities, as well as taking yes/no decisions, or simply carrying out activities. The following phrases work in any rulebook:

rule succeeds with result (...)
rule fails with result (...)

The result can be a room, a thing or a text. It can be referred to as

the result of the rule

which is nothing if the rule ended without success or failure.

Thus, "the result of the rule" will refer to the result of whatever rule or rulebook we last consulted. Similarly, "if rule succeeded" and "if rule failed" will tell us how the last-consulted rule or rulebook ended.

(This is in fact what is happening in our "audibility rules" example: writing "low background noise" is exactly equivalent to writing

rule succeeds with result the low background noise outcome;

but is evidently more concise and easier to remember. The values "the result of the rule" and "the outcome of the rulebook" are actually the same, because the result of following a rulebook is the result of the rule which stops it.)


347
*** Example  Tilt 2
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.

RB

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.

"Tilt"

Section 1 - Cards

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.

52 cards are in the card repository.

To say (count - a number) as a card value:
    choose row count in the Table of Value Names;
    say "[term entry]".

Rule for printing the name of a card (called target):
    say "[rank of the target as a card value] of [suit of the target]"

Table of Value Names
term   value   topic   
"ace"   "1"   "ace/A/one"   
"deuce"   "2"   "deuce/two"   
"three"   "3"   "three"   
"four"   "4"   "four"   
"five"   "5"   "five"   
"six"   "6"   "six"   
"seven"   "7"   "seven"   
"eight"   "8"   "eight"   
"nine"   "9"   "nine"   
"ten"   "10"   "ten"   
"jack"   "11"   "jack/knave/J"   
"queen"   "12"   "queen/Q"   
"king"   "13"   "king/K"   

After reading a command:
    if the player's command includes "of [suit]"
    begin;
        while the player's command includes "of", cut the matched text;
    end if;
    repeat through the Table of Value Names
    begin;
        while the player's command includes topic entry, replace the matched text with value entry;
    end repeat.

When play begins:
    reconstitute deck.

To reconstitute deck:
    let current suit be hearts;
    now every card is in the card repository;
    while a card is in the card repository
    begin;
        repeat with current rank running from 1 to 13
        begin;
            let item be a random card in card repository;
            change rank of item to current rank;
            change suit of item to current suit;
            now item is in the deck of cards;
        end repeat;
        change current suit to the suit after the current suit;
    end while.

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):
    let N be the number of members of the described set;
    let R be N divided by 5;
    let total be R times 5;
    decide on total.

Rule for printing room description details of something: do nothing instead.

Section 3 - Drawing and Discarding Actions

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:
    change the card drawn to a random card which is in the deck of cards.

Check drawing:
    if the card drawn is nothing, say "The deck is completely depleted." instead.

Check drawing:
    if the number of cards carried by the player is greater than four,
        say "This is a five-card game; you must discard something before drawing anything further." instead.

Carry out drawing:
    move the card drawn to the player.

Report drawing:
    say "You draw [a card drawn]."

Understand "discard [card]" as discarding. Discarding is an action applying to one thing.

Check discarding:
    if the player does not carry the noun, say "You can only discard cards from your own hand." instead.

Carry out discarding:
    now the noun is in the discard pile;
    if the discard pile is not visible, move the discard pile to the location.

Report discarding:
    say "You toss [the noun] nonchalantly onto the discard pile."

New material begins here. We want to start by grouping cards together, but identifying poker hands only if the player holds a full five cards.

Section 4 - Assessing Hands

Before listing contents while taking inventory: group cards together.

Before grouping together cards:
    if the number of cards carried by the player is 5
    begin;
        say "[run paragraph on]";
        follow the hand-ranking rules;
        if the rule succeeded, say "[the outcome of the rulebook]";
        otherwise say "some random cards";
        if the outcome of the rulebook is pair outcome, say " of [rank of the first thing held by the player as a card value]s";
    otherwise;
        say "[number of cards carried by the player in words] assorted cards";
    end if;
    say " (";

Rule for grouping together cards:
    say "[list hand]".

To say list hand:
    let chosen card be the first thing held by the player;
    while chosen card is a card
    begin;
        say "[chosen card]";
        now chosen card is the next thing held after chosen card;
        if chosen card is a card, say ", ";
    end while.

After grouping together cards:
    say ")";

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.

The hand-ranking rulebook has a truth state called the flushness.
The hand-ranking rulebook has a truth state called the straightness.

The hand-ranking rulebook has a number called the pair count.
The hand-ranking rulebook has a number called the triple count.
The hand-ranking rulebook has a number called the quadruple count.

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.

Definition: a card is high if its rank is 11 or more.
Definition: a card is low if its rank is 4 or less.

A hand-ranking rule (this is the initial sort rule):
    now every card is unsorted;
    while the player carries an unsorted card
    begin;
        let item be the lowest unsorted card held by the player;
        move item to the player;
        now the item is sorted;
    end while;
    if sort-debugging is true, say "-- after initial sort: [list hand]".

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, change flushness to 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.

A hand-ranking rule (this is the finding straightness rule):
    change straightness to true;
    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
    begin;
        change the test rank to the current rank;
        if the player carries a matching card
        begin;
            do nothing;
        otherwise;
            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]
            otherwise change straightness to false;
        end if;
    end repeat.

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.

A card can be quadrupled, tripled, paired or uncombined.

Test rank is a number that varies. Definition: a card is matching if its rank is the test rank.

This definition is a convenience so that we don't have to write so many explicit loops in the following rule:

A hand-ranking rule (this is the counting multiples rule):
    now every card is uncombined;
    repeat with current rank running from 1 to 13
    begin;
        change test rank to current rank;
        let N be the number of matching cards held by the player;
        if N is 4
        begin;
            increase the quadruple count by 1;
            now every matching card held by the player is quadrupled;
        end if;
        if N is 3
        begin;
            increase the triple count by 1;
            now every matching card held by the player is tripled;
        end if;
        if N is 2
        begin;
            increase the pair count by 1;
            now every matching card held by the player is paired;
        end if;
    end repeat;

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 the straightness is true and the lowest card carried by the player is an ace card and the rank of the highest card carried by the player is 5,
        do nothing;
    otherwise
        now every ace card which is carried by the player is carried by the player;
    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
    begin;
        let selection be the lowest paired card which is carried by the player;
        move the selection to the player;
        now the selection is uncombined;
    end while;
    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
    begin;
        repeat with item running through ace cards which are carried by the player
        begin;
            move item to the player;
        end repeat;
    end if;
    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
    begin;
        let selection be the lowest tripled card which is carried by the player;
        move the selection to the player;
        now the selection is uncombined;
    end while;
    while the player carries a quadrupled card
    begin;
        let selection be the lowest quadrupled card which is carried by the player;
        move the selection to the player;
        now the selection is uncombined;
    end while;
    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.

A hand-ranking rule (this is the four-of-a-kind rule):
    if the quadruple count is 1, four of a kind.

A hand-ranking rule (this is the full-house rule):
    if the pair count is 1 and the triple count is 1, full house.

A hand-ranking rule (this is the flushes rule):
    if flushness is true, flush.

A hand-ranking rule (this is the straights rule):
    if straightness is true, straight.

A hand-ranking rule (this is the three-of-a-kind rule):
    if triple count is 1, three of a kind.

A hand-ranking rule (this is the two-pair rule):
    if the pair count is 2, two pairs.

A hand-ranking rule (this is the pair rule):
    if the pair count is 1, pair.

A hand-ranking rule (this is the default rule):
    high card.

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.

Sort-debugging is a truth state that varies.

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.

Understand "debug sorting" as debugging hand sorting. Debugging hand sorting is an action out of world.

Carry out debugging hand sorting:
    if sort-debugging is false, now sort-debugging is true;
    otherwise now sort-debugging is false.

Report debugging hand sorting:
    say "Sort debugging is now [if sort-debugging is true]on[otherwise]off[end if]."

Test me with "draw / g / g / g / g / force hand / g / g / g / g / g / g / g / g / g / g / g / g".

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.

Table of Testing Hands
set suit   set rank   
spades   1   [royal flush]   
spades   13   
spades   12   
spades   11   
spades   10   
clubs   12   [straight flush]   
clubs   11   
clubs   10   
clubs   9   
clubs   8   
diamonds   8   [four of a kind]   
hearts   8   
spades   8   
clubs   8   
clubs   3   
clubs   1   [full house]   
spades   1   
hearts   10   
spades   10   
clubs   10   
hearts   2   [flush]   
hearts   5   
hearts   7   
hearts   11   
hearts   12   
hearts   1   [straight]   
spades   13   
diamonds   12   
clubs   11   
hearts   10   
hearts   2   [three of a kind]   
spades   2   
clubs   2   
clubs   4   
spades   3   
diamonds   6   [two pairs]   
spades   6   
clubs   7   
diamonds   7   
hearts   9   
diamonds   6   [two pairs, ace high]   
spades   6   
clubs   1   
diamonds   7   
hearts   1   
hearts   12   [pair]   
spades   12   
diamonds   10   
spades   7   
clubs   4   
diamonds   13   [high]   
hearts   11   
spades   9   
clubs   7   
diamonds   5   
hearts   1   [tricky sorting: low straight]   
diamonds   2   
spades   3   
diamonds   4   
diamonds   5   

Understand "force hand" as forcing a hand. Forcing a hand is an action out of world.

Current marker is a number that varies.

Carry out forcing a hand:
    repeat with item running through cards which are carried by the player
    begin;
        increase current marker by 1;
        if current marker is greater than the number of filled rows in the Table of Testing Hands, change current marker to 1;
        choose row current marker in the Table of Testing Hands;
        change the suit of item to the set suit entry;
        change the rank of item to the set rank entry;
    end repeat.

Report forcing a hand:
    try taking inventory.


PreviousContentsNext