CS231

Monte-Carlo Simulation: Blackjack

The main purpose of this project is to give you practice building classes in Java. To do this, we'll simulate a simple version of the card game Blackjack. The objects in a card game include: a Card, a Deck, a Hand, and Game. You'll make a class for each one, connecting them together as appropriate. The Deck and Hand classes will rely on your ArrayList implementation from the lab.

Project Checklist: Before submitting your project, make sure you have completed all of the following!

All of the coding work listed under tasks
Your report describing the work you did in the project
Your extensions should you choose to do any

Tasks

For this assignment you will implement classes to represent a card, a hand, a deck, and the game Blackjack. The result will be a text-based version of the game that runs in the terminal. You are free to make the game more complex as an extension. (Please see "Submitting Projects" on the main Projects page for a reminder about how to submit your extensions!)

The purpose of the assignment is not to create a Blackjack game for people to play, however, but to study the properties of Blackjack, given a particular rule set, when played over many hands. You are using CS to study the properties of a system defined by a set of rules.

For this project, we have provided small testing programs that will test the functionality of your code. In future projects, you will write these tests yourselves, but we felt that for the first two projects it would be nice if we gave you good starting examples.

More information about Blackjack.

Basic Blackjack Rules

The link above contains an extensive description of the full rules of Blackjack. For this project, you are required to implement only a simplified rule set. You can implement more of the rules as part of project extensions.

There will be only two players in the game: the player and the house. In our simplified rule set, an ace is worth 11 points. In an actual game, an ace can be either 1 or 11. Play should use the following procedure.

The player and the house should each receive two cards dealt from a deck
The player should play their entire turn before the dealer.
- The player should calculate the value of their hand (the sum of the card values) and choose whether to take a card (hit) or stop at the current value (stand).
- If the player chooses to hit, then if the new value of their hand is greater than 21, the player loses (busts) and the game is over. If the value is less than 21, the player repeats the process until they stand or bust.
If the player did not bust, the dealer plays.
- The dealer will continue to take a card (hit) until the value of their hand is 17 or greater.
- If the dealer busts, then the player wins.
If player and dealer both avoided a bust, then the hand with the highest value wins the game. If both hands are of equal value, then the hand is a tie (push).

When playing Blackjack, the deck is usually not rebuilt and shuffled between each game. Instead, the deck is rebuilt and shuffled when it gets below a certain number of cards. You will implement the rule that when there are fewer than 26 cards (out of 52), then the deck should be rebuilt to 52 cards and shuffled. Therefore, shuffling should not be done every game, but should be an action that is conditioned on the number of cards left in the deck. How often the deck is shuffled will affect game play because it affects the probabilities of certain cards appearing.

The Card Class

Download the following two files: Card.java and CardTests.java. In this section you will complete the java class called Card, which should hold all information unique to the card. For this assignment, it needs to hold only the value of the card, which must be in the range 2-11 (or 1 - 11 if you implement aces with optional values of 1 or 11). The Card class should have the following methods.

public Card(int v) a constructor with the value of the card, possibly doing range checking.
public int getValue() return the numeric value of the card.
public String toString() return a string that represents the Card object. This will override the default toString method in the Object class. Due to the way we have implemented the CardTests class, we expect that it will simply return the String version of the value. That is, a card of value 5 will create the string "5", etc.

When you have completed the methods above, run the CardTests program by compiling it and executing java -ea CardTests in your terminal/cmd.

The Hand Class

Download the following two files: Hand.java and HandTests.java. In this section, complete the java class called Hand, which should hold a set of cards. You must use your ArrayList implementation from lab to hold the Card objects. The class should have at least the following methods.

public Hand() initialize the ArrayList.
public void reset() reset the hand to empty.
public void add( Card card ) add the card object to the hand.
public int size() returns the number of cards in the hand.
public Card getCard( int i ) returns the card with index i. Cast as appropriate.
public int getTotalValue() returns the sum of the values of the cards in the hand.
public String toString() returns a String that has the contents of the hand and the total value presented in a nice format. Use the Card toString method (implicitly or explicitly) to accomplish this. Due to the way we have implemented the HandTests class, we expect that a Hand object containing values 2, 3, 4 (in that order) will create the string "[2, 3, 4] : 9".

When you have completed the methods above, run the HandTests program by compiling it and executing java -ea HandTests in your terminal/cmd.

The Deck Class

Download the following two files: Deck.java and DeckTests.java. Create a java class called Deck, which should hold a set of cards and be able to shuffle and deal the cards. You must use your ArrayList implementation from lab to hold the cards. The class should support the following methods.

public Deck() builds a deck of 52 cards, 4 each of cards with values 2-9 and 11, and 16 cards with the value 10. Note, you probably want the constructor to call the build() method, below.
public void build() builds a deck of 52 cards, 4 each of cards with values 2-9 and 11, and 16 cards with the value 10.
public int size() returns the number of cards in the deck.
public Card deal() returns the top card (position zero) and removes it from the deck.
public void shuffle() shuffles the deck. This method should put the deck in a uniformly random order. Refer back to the lab for some hints to get you started!
public String toString() returns a String that has the contents of the deck "written" in a nice format (so that you can see the ordering of the card values).

When you have completed the methods above, run the DeckTests program.

The Blackjack Class

Download the following file: BlackjackTests.java. In this section create a class called Blackjack (no skeleton file for you this time! Do your best to make it clean) that implements a simple version of the card game. The class will need to have fields for a Deck, a Hand for the player, and a Hand for the dealer. The main function for the Blackjack class should implement one complete game.

public Blackjack() this constructor should set up a game. You can avoid duplicate code by calling the reset() method.
public void reset() should reset the game. Both the player Hand and dealer Hand should start with no cards. If the number of cards in the deck is less than 26 (the reshuffle cutoff), then the method should create a fresh (complete), shuffled deck. Otherwise, it should not modify the deck, just clear the player and dealer hands.
public void deal() should deal out two cards to both players from the Deck.
public boolean playerTurn() have the player draw cards until the total value of the player's hand is equal to or above 16. The method should return false if the player goes over 21 (bust).
public boolean dealerTurn() have the dealer draw cards until the total of the dealer's hand is equal to or above 17. The method should return false if the dealer goes over 21.
public String toString() returns a String that has represents the state of the game. It may be helpful to show the player and dealer hands as well as their current total value.

Use the main function of your Blackjack class to test the above functions. Make sure they are working properly by dealing two hands and then calling the playerTurn and dealerTurn methods, printing out the game state and making sure the rules are correctly implemented.

Create a method to play a single game.

public int game(boolean verbose) the game method should play a single game of Blackjack following the procedure outlined above. The game method should call the reset method at the start of each game. The game method should return a -1 if the dealer wins, 0 in case of a push (tie), and a 1 if the player wins.
If the parameter verbose is true, then the game method should print out the initial and final hands of the game and a statement about the result (dealer/push/player).

The attached BlackJackTests program is extremely bare-bones. Update it verify that your game results in the expected number of outcomes of each type (player win, dealer win, draws).

Storing Game Output

Once you have completed the above four classes, generate a printout of three different games. You can send output to a file using the greater than symbol on the command line. For example, the command

java Blackjack > mygames.txt

would play a game and send it to the file mygames.txt. Please include these in the results section of your report!

Simulation

Make one more class called Simulation. This class should have only a main function that generates and prints (nicely formatted so we know what each number represents) the results asked for in the exploration section. Note that the code should create and re-use a single Blackjack object for each set of simulations. It should keep track, for that set of simulations, how many games the player wins, how many the dealer wins, and how many are pushes. Make sure that your Simulation file can be run once to generate all of the results asked for in the exploration section and discussed in your report (i.e. we shouldn't need to open it and change the number of simulations manually to get different results.)

Exploration

Your final task is to explore how the results vary across different numbers of games used in the simulation. Compute and print the game outcome statistics (percent draw, player win and dealer win) when running 100 simulations, 1000 simulations and 10,000 simulations. How much variation do you see across your results? Make sure that your Simulation.java file can be run with no user input or manual changes to replicate these results. Also make sure to include and discuss them in the results section of your report. Based on these results, do you think your Blackjack implementation is fair for the player? How likely do you think a player would be to notice this if they played 10 games? Please referemce specific results generated by your Simulation file when discussing your answer.

Extensions

Please see "Submitting Projects" on the main Projects page for a reminder about how to submit your extensions!

Projects are your opportunity to learn by doing. They are also an opportunity to explore and try out new things. Rather than list out every activity for a project, the defined part of each project will be about 85% of the assignment. You are free to stop there and hand in your work. If you do all of the required tasks and do them well, you will earn a B/B+.

To earn a higher grade, you can undertake one or more extensions. The difficulty and quality of the extension or extensions will determine your final grade for the assignment. Extensions are your opportunity to customize the assignment by doing something of interest to you. Each week we will suggest some things to try, but you are free to choose your own.

A common question is "how much is an extension worth?" The answer to that question depends on the extension, how well it is done, and how far you pushed it. As teachers, we prefer to see one significant extension, done well, where you explore a topic in some depth. But doing 2-3 simpler extensions is also fine, if that's what you want to do. Choose extensions that you find interesting and challenging.

The following are a few suggestions on things you can do as extensions to this assignment. You are free to choose other extensions, and we are happy to discuss ideas with you. For full credit, extensions need to be discussed in the report adequately. For example, if you chose the second extension below, I would expect that you compared the results of the simulations with the original rules and the updated rules and reasoned about the why whatever changes did or did not take place.

Create a new method in your Blackjack class called playerTurnInteractive() that uses input from the terminal to control the player's actions. Then create a new class Interactive that lets you play Blackjack on the terminal.
Add in more of the rules for Blackjack. For example, an Ace (value 11 in the default case above) can have the value 1 or 11, whichever is more advantageous. If you add in the Ace rule, then you will also want to take into account a real Blackjack (2 cards totaling 21) when evaluating the winning hand. A Blackjack beats a 21 with more than 2 cards. See how these rules affect the simulation results.
Implement methods that allow the user to specify a reshuffle threshold. Make your game use 6 decks, and reshuffle if only 1 deck is left. Play the game 1000 times, and observe how many games the player wins, how many the dealer wins, and many are pushes. Compare with using only a single deck.
Add a type of betting strategy to the simulation and see if the player can win money even while losing more games than winning.
Try running the simulation with different numbers of games and see how variable the results are. For example, run the simulation using M games (e.g. M = 100) and do this N times (e.g. N = 10). Then calculate the standard deviation of the results. Then you can plot the standard deviation versus the number of games (M) in the simulation to see how the results stabilize as you use a larger number of games.

Congrats, you're done with everything except for your project report where you will communicate your findings from all that code! Make sure to submit your code on Gradescope. The project report is an important part of the work in this project, so don't forget to do it!

Please see "Submitting Projects" on the main Projects page for a reminder about how to submit your project to Gradescope!