Mini-Assignment B: Game Books

Due Tuesday, February 26th at 7:00 PM or Monday, March 3rd at 7:00 PM
(There are a few points of extra credit for turning in at the earlier due date.)

Java concepts I want you to learn from this assignment:

Reinforce how to write a complete Java class with instance fields, constructors, methods, return values and parameters
How to use if statements
How to use null
How to use a Scanner to get user input

Other goals:

Prepare you for the first exam
Give you experience using a provided class
Give you experience fitting pieces together

Files:
miniB.jar
AdventureApp.java
exam.txt
concert.txt

Intro:
On of the troubles with reading books is that they are not interactive and they are the same every time you read them. One solution is game books, which let the user decide how the story will develop. The most popular series, perhaps is the Choose Your Own Adventure series.

The basic idea is that at certain points the reader must make decisions for the main character. The course of the story and the ending depend on how the user chooses. If you choose one way, the book might instruct you to turn to page 21 and if you choose the other way you may be told to go to page 35. You flip to the specified page and start reading there. Typically, making bad choices will result in failure or death, while making many correct decisions will result in eventually winning. I've written a very short sample adventure made of .html pages that you can try.

If you want to try some more, there are .html game books online. Unfortunately, I was unable to find free PG game books to link to, so these are all pretty much PG-13. You've been warned.

You can visit the Bunching Shuttlecocks, which has a few simple adventures.
331 Oakmount Drive is a horror adventure that seems only partly finished.
You can try Zap Dramatic if you want to see animated adventure books
You can try the incredible horror game book Mansion of Maleficence if you have dice and want a more intricate challenge.
If you want a much more complicated system and have lots of time, the Lone Wolf books are online.

Unlike the ones I've shown you online, the one's you will be creating will run from the console. The story and choices will be printed to System.out and the user's decisions will come through System.in. A sample run of the program using the sample adventure can give you a feel for what you're doing.

You will write a simple class called Choice, which will have some text and the destination page number. You will write the Page class, which will have text and up to three Choices. I will provide you with the Book class, which holds many pages. To connect it with console input, I've started a AdventureApp class, which you will need to finish.

The Choice class
The Choice class is extremely simple. Each Choice has a description of the action that class would take and a page number to flip to if that choice is taken. Check the javadoc for a list of methods and constructors.

Examples: the first Choice on the first Page of the sample adventure has the text "Just keep sleeping" and it leads you to page 4 (which is not displayed). The second Choice says "Get up in five minutes" and it takes you to page 3.

If you have difficulty with this class, you may want to talk to me before the exam.

The Page class

Each Page has a page number, a piece of the story, and 0 to 3 choices. If a Page with no Choices is reached, the game is over, so any Page with no choices should let the user know if the game was won. (BIG HINT) Since you have up to three Choices to remember (and since we haven't covered better ways to do this), you had better have at least three data members that can hold Choices.

Examples: in the sample adventure the first Page is page number one and it has the text "The first thing you notice ... What do you do?" and three Choices. If you click the first choice, you go to the Page with page number four, the text "The next day ... of your grade" and zero choices.

The Page class will probably be the trickiest class of this assignment, so I'll run over the five methods and four constructors you will need to write.

There are four constructors. All four take a page number and some text. One is for creating a Page with three choices, one for creating a Page with two Choices, one for creating a Page with one Choice and (sensing a pattern?) one for creating a Page with zero choices. (BIG HINT) Since all of the Pages must have the same number of Choice data members, any variables that are unused should be set to null (which means no Choice object).
The getPageNumber() and getText() methods should be easy.
The isEndOfStory() method returns a boolean--either true or false. It should return false if and there are any Choices. It should return true if the page has no Choices.
The printText() method tells the Page to print itself to the console. It should print out the text of the Page as well as a numbered list of the choices. If there are three Choices, the Choices should be numbered 1, 2, 3 even if the page numbers from those choices are completely different. The sample run shows an acceptable format. You might also want to print some decorations, the page numbers or things like that if you think it's a good idea. Notice that it should only print available options--if there is only two Choices, then only offer those two choices.
The getChoice() method takes in an int and returns a Choice. The tricky part is that each Choice is associated with two numbers--the number the user types to select it (the one printed in printText()) and the page number the choice leads to. This operates on the number the user types in, so getChoice(1) should give the first choice. If there is no Choice corresponding to the number, this method should return null. So getChoice(-23234) and getChoice(5) always return null. On the other hand, getChoice(2) returns null only if there is less than two choices--otherwise it returns the second choice.

Since we are interacting with a user, we will count Choices from 1--other wise we will confuse the user.

The Book class

You don't need to write the Book class--I wrote it for you. It is contained in miniB.jar, which you should download and add to your project directory. Referesh your project and "Add External Jars" it from the Java Build Path just as you did with miniA.jar.

A Book is made up of various Pages. It holds them all together instead of forcing you to make a separate variable for each Page. You can use the constructor with no parameters to make a Book with no Pages, then you can use the addPage() method to add Pages you have created one at a time. You can get the total number of pages with getNumberOfPages() and you can retrieve a Page with a given number with the getPage() method.

All pages must be one or greater--there is no technical reason for this--it is just because having a page number -23 or 0 feels strange. Also, for obvious reasons, you can't have two pages with the same number. The adventure should start on page one.

If you like the .html versions of game books and you'd like to convert a Book object to .html files, then you may call the outputBookToHTML(), which is what I used to make the online version of the sample adventure.

If you want to write a really complicated text adventure, it would probably be frustrating to write it by manually creating Pages and Choices. If you write your sample adventure in a very specific way and save it to a .txt file, you can create a Book by passing in the file name and your game book will be created automagically. To see what the format look like, you can see the .txt file I used to create the sample adventure.

You aren't required to learn these rules and create an adventure this way, but it's not hard and it can save you some trouble:

The file should be a .txt file that consists of a list of Pages.
Each Page starts out with a # followed by the page number followed by the page text.
After the page text comes a list of up to three Choices
Each choice starts with a . followed by the destination page number followed by the choice description.
No words can start with . or # in your Choices or Page descriptions (since they are used to determine where text begins and ends)
Like in Java, line breaks and white space are mostly ignored. If you with to to include a line break, you may write \n as a word by itself.

If you want a more difficult challenge, try concert.txt, which I read part of in class. Since it's a reward for completing your assignment, I haven't posted an .html version.

The AdventureApp class

Start by downloading AdventureApp.java, which is about half written. You get a head start for three reasons:

It uses a loop, which we have not yet covered
The assignment is big enough already
The algorithm is a little tricky

The comments should tell you what you need to write and where you need to write it--follow them closely. When you are done, you should be able to run the program, and it should look a bit the sample run, though you may make it prettier if you'd like.

When you hand in your project and I run your AdventureApp, I want to see it run with your own original game book. You may either create it with your own Java code or you must write it as a file and write the code to load it.

I expect your game book to have:

At least 8 Pages
At least one good ending
At least two bad endings
At least one Page with 3 Choices
At least one Page with 2 Choices
At least one Page with 1 Choice.
At least vaguely interesting

You may send me as many adventures as you would like.

Turning this in

Be sure to follow the course style and commenting guides--lots of people lost points here and they are the easiest points to get. If you work in pairs, follow the pair programming guidelines and have BOTH partners send me a readme.txt. Do not use the course handin program, since it isn't set up for the mini-assignments.

Recall that the course policy is not to accept late work.

The files I want from everyone are:
Choice.java
Page.java
AdventureApp.java

If you opted to write any adventures by a text file:
myAdventure.txt

Pair partners:
README.txt from both partners

Possible extra credit if you send me something that shows me you did something above and beyond what is required. Here are some ideas:

Write an excellent text adventure
Show me that you've put one of your text adventures online
Give me a very complete description of what you would do to the Page class to let each Page have as many choices as I want.
Write some good tester classes for Page and Counter, preferably with good use of if statements.
Send me good javadoc
Do something so cool I can't even predict it.

Please email the files to Tim Bahls. Send them to bahls AT wisc.edu. If you know how, please put them in a .zip file.

Last updated 2-26-2008