CS100M Fall 2004
Project 3 Part A
Due Thursday 10/7 at 3pm

Objectives and Instructions
This project will give you practice with four new programming concepts: There are two parts. Part A gives you your first chance to write a fairly large program from scratch. We'll provide some function headers and an overview of how to put the pieces together, but you'll have a lot more freedom than in previous assignments. Part B contains a shorter problem dealing with 2-d arrays--matrices. Part B will be posted once we introduce matrices in class.

Hints & Help
If you need help on the project, do not hesitate to go to any course staff's office hours or schedule an appointment. Also, we strongly recommend that you check the newsgroup. There are several reasons to do this: If you're having problems with the Gravity newsreader (despite the help page given in an 9/6 course announcement), try typing the following in your browser's address bar: 
    news://newsstand.cit.cornell.edu/cornell.class.cs100m
This will open your browser's default news reader (probably Outlook Express) for reading messages. You might have to fiddle with settings to get it to let you post messages.

And, as with all assignments, start early!

Part A: Texas Hold'em
If you've watched ESPN in the last year, you've probably noticed that poker, especially "Texas Hold 'em," has become inexplicably popular on TV. You're part of a new start-up company called FadCorp that seeks to turn a profit by programming an implementation of "Texas Hold 'em" in MATLAB. This will be sold to engineers and scientists everywhere, who would love to take a break from MATLAB programming by playing poker, if only someone would write the code...

Game Rules
The rules of Texas Hold 'em are very simple. All players are dealt two cards, face down. Once they look at their cards, there is a round of betting. Then three new cards are placed face up in the center of the table. This is known as the "flop." These cards can be used by all players in making their hands. Another round of betting ensues, and then a fourth card is placed face up. The players bet again, and then the fifth and final card is placed face up. After the players bet one last time, everyone shows his/her cards; whoever can make the best five-card hand using the five face-up cards and the two that they were dealt wins. If you want a more thorough overview of Texas Hold 'em, check out a Texas Hold'em link. We've given you enough information here though for your project.

What you will program
Since you (the player) are going to be running this game on your own computer, there's really no one to bet against. So you don't have to have any betting in program--in fact, we ask that you keep betting out of any code you submit, since we don't want to encourage gambling. Also, since you're the only player, you don't have to have support for a variable number of players. There will be only two hands, your hand and a "computer player hand." Note that since there is no betting, you don't actually get to make any choices, you just get to see the five cards flipped up. Also, you'll be provided with a function that can look at two hands and determine which is better--this is a surprisingly hard function to write correctly so we will provide the code later on!

What you do have to program is everything else.
(revised 10/1)
The user should see the following output from your program in this order:
  1. The two cards that were dealt to the player and the two cards that the computer opponent was dealt
  2. The three cards that comprise the "flop"
  3. The fourth card
  4. The fifth card
  5. A summary of the seven cards the player and the computer opponent can use to make their hands
  6. A message describing who has won
  7. The cards of the player who has won
Program functionality will be encapsulated in four functions, listed below:
Additional Information
You should keep track of the "cards" as numbers from 1 to 52. Do not try to keep track of a suit and a value all the time--you only need to know the suit and value when you display the cards (in the showCard function). The rest of the time you should store the cards as numbers from 1 to 52. This means that your drawCard() function should return a number from 1 to 52. You'll find that this makes things easier in the long run.

Using this method of representation, numbers 1-13 represent the Hearts, with 1 being the Ace of Hearts and 13 being the King. Likewise, 14-26 represent Diamonds, with 14 being the Ace of Diamonds and 26 being the King. Then 27-39 represent Clubs and 40-52 represent Spades. You'll need this information to write the showCard function.

Design and style considerations (revised 10/1)
Remember that global variables should be used sparingly as discussed in class. A solution that uses many global variables, say more than two or three in this project, shows poor design and will be penalized. As always, use good programming style as we have discussed in class. Commenting is always important and it is exceptionally so in this project because you need to explain your design clearly. A good program should be relatively efficient and the code should not be redundant. We give you freedom to design you own display for the cards and we hope that you'll have fun with it. However, particularly poor displays (such as displaying "King" as 13) or displays that take way too long to draw are bad designs and will be penalized in grading.

Function cardEval (to be provided later):
[winner_string, loser_string, winner_number] = cardEval(cards1,cards2)
We are providing you with a function with the above header to determine who has "won" the game. You don't have to modify the code inside cardEval.m at all, but you can look at it if you want. You'll see that this function is big and ugly, but it probably doesn't contain anything new to you. We want you to focus on organizing and writing your program, not on the intricacies of poker scoring.

This function takes in as input arguments two vectors of seven "cards"--the function expects two vectors of length seven where each cell contains a number in(1..52). See "Additional Information" above for details. The function returns three values:
  1. winner_string: a string describing the hand held by the winning player. (E.g., "A pair of Jacks")
  2. loser_string: a string describing the cards hand by the losing player.
  3. winner_number: a number that denotes which player won. If cards1 is better than cards2, winner_number will be 1. If cards2 is better, winner_number will be 2. If the hands tie, winner_number will be 0.

Hints
As you write each function, make sure that it works before moving on to the next! For example, once you have drawCard written, it will be smart to make sure that 52 calls to function drawCard gives you 52 different cards. If you don't test this function independently, a bug that gives you "wrong" cards will be very difficult to catch since in each run of the overall program you see only nine cards.

To make your playPoker function "wait" so that the players can think about the cards, instead of just showing all seven cards quickly, you could either ask for input (i.e. input('Press enter to see the flop!') or just pause for a few seconds (i.e. pause(3) ).

Since there're no choices for the user to make, feel free to show the computer player's cards at the beginning. For added suspense, you could wait to show them at the end. In either case, make sure to let the user know whose cards they're looking at!

What to Submit for Part A
Before the deadline, submit via CMS the four functions you have written: drawCard.m,showCard.m,showHand.m, and playPoker.m. Do not change the function headers from what is listed above! We need the headers to match so that they will work with our test code. Be sure to adequately comment your code and use vectors where appropriate.