Assignment 07

Task

Write your choice of one of three GUI games that can run as either a windowed application or as an applet.

Text: Java Tutorial: Swing
Concepts: GUIs.

Requirements

Step 0: Pick your game

Your options include:

Tic-Tac-Toe (tips)

This should be a human-vs-computer game. You can just have the computer select a random open square as its move, though. However, you can earn additional points if your computer AI opponent actually has some strategy to it.

Concentration (example)

At its simplest, this can just be a grid of buttons that you click to reveal up to two at a time. You can just reveal letters, or you can get inventive and use images, words and their definitions, etc.

Minesweeper

Basically like the classic Windows game. Marking mines with flags and the two-button click that clears all surrounding squares are optional features. This game is harder to implement, though, so it is worth extra points.

Step 1: GUI

Construct a GUI for your game. It should contain at least a grid of buttons. These buttons can start blank to show they are "empty" squares. When the player clicks on one, it should change appropriately. (TicTacToe: Change to an X or O; Concentration: Reveal the underlying word/image; Minesweeper: Reveal the underlying bomb or number.) You should disable clicked button (as appropriate) to prevent the player from changing a button that already shows a move.

The game must end on the appropriate conditions. (TicTacToe: either someone wins with 3 of the same characters in a row or there are no more empty squares; Concentration: All matching pairs have been uncovered; Minesweeper: The user clicks a mine or uncovers all non-mine squares.) You should report the final game outcome to the user. Once the user has had a chance to read that message, you can start a new game or provide some means (such as a Replay or Reset button) for the user to do so.

These are only the basic requirements. You are encouraged to go beyond this. A few ideas include:

• Nicer-looking buttons/widgets (maybe using images or icons)
• A JFrame window starts off at an decent size and centered on the screen.
• Alternate whether the computer or player gets to make the first move (TicTacToe)
• Keep a running score or a count of games won/lost
• Use keybinding/mnemonics so the game is easily played with the keyboard (good for speed games).
• Use a timer for speed games--maybe most wins in a minute?
• A menu of relevant actions, such as to quit, or to allow the player to select whether they want to play X or O, or other options (such as game difficulty or AI used, or a next move hint as suggested by the AI).
• Etc.

You can earn up to +15 points for particularly nice GUI improvements and options. You can also earn up to another 15 additional points depending on the complexity of your game or its AI:

• TicTacToe: Computer opponent chooses squares randomly. +0
• Concentration: +5
• TicTacToe: Some basic AI strategy. +10
• Minesweeper: Random mine placement, contiguous empty squares are revealed properly. +10
• TicTacToe: Optimal AI strategy. +15

You may write additional classes as needed, but your main executable/JApplet class should be UsernameA07.

Step 2: Applet

Your main class should also be a JApplet that runs embedded in a webpage. (It is possible for applets to popup a JFrame window, but don't do that. Instead, keep the applet content in the webpage itself.) Create the necessary HTML page. This page should have additional info too, such as a description of the game and a link to the associated documentation.

Step 3: Extract documentation

Make sure all of your methods are documented. In the overview documentation for your main class, describe/list any extra credit enhancements you made or any existing bugs or problems. Also, you must include the full URL in the documentation to a working version of your applet on www2.hawaii.edu.

Run the javadoc tool to extract your documentation into HTML pages. Upload all of these pages to www2.hawaii.edu, preferably in a single subdirectory. As mentioned, your applet page should contain a link to the index.html page of this extracted documentation.

Sample output

These are just examples to show you the basic idea of what you would need.

TicTacToe

I had to resize the window to make it look like this. I used the setEnabled method on the buttons to disable buttons that should not be clickable. I disable all the buttons as soon as someone wins so the user can't continue the game. Also at the end of the game, I enable the Play Again button. Clicking that returns the game to the initial state shown on the left.

Minesweeper

Mid-game

A winning game (pop-up results not shown)

A losing game (pop-up results not shown)

Thanks to Anthony Christe for the demo implementation.

What to Submit

You will upload your source code to Tamarin, but it will only check that everything compiles. Your TA will then grade your submission manually.

Create a .jar including all of your .java files and your applet's .html file. The class documentation of your main class should include the complete URL of your working applet and extracted documentation. You should not include the extracted documentation pages in jar. Upload your UsernameA07.jar file to Tamarin.

Remember to follow the course coding standards on all assignments.

Grading [60 points]

5 - Compiles

15 - Playable board

Buttons that do something when you click them (10). Prevents illegal moves, such as replacing a previous move (5). (Up to +15 more for fancy improvements.)

20 - Game logic

Appropriately generates a random board and/or responds to player moves with its own move or with appropriate response (10). The game ends correctly, reporting to the user the results to the user (ie, who won, lost, or if the game was a tie) (10). (Up to +15 more for more complex games or intelligent AI opponent.)

5 - Runs as application

Game appears in a working JFrame when the main method of UsernameA07 is run.

10 - Runs as applet

Submission includes a .html file with an embedded applet version of UsernameA07 (5). Documentation of the main UsernameA07 class also includes the URL of a working applet page on your www2.hawaii.edu website (5).

5 - Javadoc

Extracted javadoc documentation pages are also hosted on your website, with a link to them from your applet page.

Helpful Resources

• Swing Tutorial, particularly the visual guide list of components and visual guide to layouts.
• Lectures 09B and 10A, including complete code for the numberpad applet and its HTML page. (For HTML code, you can right-click the link and Save as..., then open the file using a simple text editor.)

FAQs

I used images in my GUI, and they worked fine on my machine. But when I upload my applet, it all breaks!

If you look through your Java Console, you'll probably find an error that looks like this:

Caused by: java.security.AccessControlException: access denied 
  ("java.io.FilePermission" "myimage.png" "read")

This suggests that this is a unix file permissions problem that can be fixed with the chmod command. This is not actually the case.

What's actually happening here is that the .class file has been downloaded from the server and is running in your browser on your local (client) machine. Your applet is then trying to access some file--myimage.png, in this case. But your applet is looking for that file in the same directory as itself... but, since it's now running on the user's machine, it's trying to find some file in its local directory there. But, due to the Java security sandbox, an applet does not have permission to read files on the user's machine! Hence, the exception.

This is not a problem when you run the applet directly from your local machine because it is able to access files in the same or child directories of where it came from, and both the applet and the image are then on the same computer.

The recommended fix for this is to bundle the images with your .class file in a jar file. This can be an executable jar or not. You can then use the getResource() method, which is in the class Class

Example:

  //assuming myimage.png is in the root of the jar file with all your .class files
  ImageIcon icon = new ImageIcon(this.getClass().getResource("myimage.png"));

You will need to specify in your HTML file that your applet class is now in a jar, like so:

  <applet code="UsernameA07.class" archive="UsernameA07.jar" width="200" height="180">

Good luck!

My applet won't load. I get an java.reflect.TargetInvocationException popup (on Windows) and nothing in the Java Console.

This error occurs if the applet object cannot be created and initialized. However, the current Java plugin is very unhelpful in that it does not provide the full stack trace or any information about the exception that prompted the TargetInvocationException. Therefore, you have to debug this without knowing where to look.

Here is the current list of the known causes:

Your applet class does not have a "default" constructor that takes no parameters.

Note that init() is not a static method. That means the JVM needs to build an instance of your JApplet-extending class before it can call init() and start your applet running. However, since the JVM won't know about any parameters your constructor requires, you need a constructor that takes no parameters.

You are creating a JFrame in your constructor.

Specifically, this line is the problem:

    frame.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);

This behavior will indirectly call System.exit, but an applet is not allowed to kill the JVM like that due to the applet's sandbox security restrictions. You could just comment out this line, but then your JFrame won't work properly when you run the program as an application. Besides, when run as an applet, you shouldn't create a JFrame at all.

The design solution is to create the JFrame in your main method, not in your constructor. Your constructor should only create a top-level JPanel. (See the NumberPad demo code above for example main and init methods.)

If your problem is not one of those listed here, look for other reasons why your constructor or init() method might generate an exception.