Final Project:
Archaeological Dig Simulation

In this project you will design and implement a modified version of an Archaeological Dig Simulation that behaves a lot like the solitaire computer game MineSweeper.

Problem Specification:

Design a program to simulate an archaeological dig. The goal is to dig near ancient artifacts buried in the soil to loosen them and make it easy for the archaeologists to extract them manually. If you dig too close to the artifacts, though, you will damage them. The archaeologists have mapped out the dig site as a grid. The chemistry department has come up with a soil test to see whether there are artifacts close by, either in the current grid location or in an adjacent location. Your job is to dig in the grid blocks without artifacts and to leave the blocks with artifacts alone. Since this is such an important project, the archaeological team wants their students to be able to practice this before they get to the dig. You are going to write the simulation that the students can use to practice.

Program Specification:

• The simulation consists of a square grid representing the dig site.  The grid contains artifacts in various locations, and the number and location of the artifacts should change every time the simulation is run.   In particular, there should be no fewer than 5 artifacts and no more than about 10% of the number of cells in the grid. Each artifact should be placed at a random location in the grid and no two artifacts should be placed at the same place.
• When the simulation starts the grid appears empty, representing the site before any digging has taken place. All blocks should be "invisible"; that is, they should not indicate whether they contain an artifact, are adjacent to one or more artifacts, or are nowhere near any artifacts.
• Clicking on a grid block represents digging in that location. When a user clicks on one of the blocks in the grid they are given feedback depending on the contents of the block and its neighbors. In particular,
  • If the block contains an artifact, the display should show the artifact that has been exposed and damaged.  This could be done as simply as displaying an "A" for artifact in the grid cell, or by displaying a picture of an artifact. Damaging an artifact ends the simulation.
  • If the block does not contain an artifact but is adjacent to one or more blocks that do contain artifacts, the block should display the number of artifacts adjacent to that block.
  • If the block does not contain an artifact and the block is not adjacent to any artifacts, the block should indicate that the block is empty. The user should be able to visually distinguish between a block where they have dug and found nothing and a block where they have not yet dug; for example, you might display a dash or some other character in blocks where users has dug and found nothing.
• The user continues to click on blocks until they click on an artifact, ending the simulation, or until they have clicked on all the blocks not containing artifacts, successfully completing the dig.

Classes to Get Started:

Since we have not yet talked in class about how to develop graphical user interfaces, we are providing two classes, ArchSimGUI and ArchSimDisplay.  The user interface responds to certain user actions, such as pressing the Restart button or clicking the mouse within a cell in the grid, but it does not know what actions to perform when these events occur.  It requires a class with which it can interact that does know what actions to perform.  Therefore, we have created an interface, ArchSimulation, that specifies a set of methods that the GUI can invoke.  The display class also has some special requirements; it assumes that the objects in the grid are not just normal GridObject instances, but that they are instances of a class that has an isVisible method so that the display can tell which objects in the display it should show and which should remain hidden.  We have provided a skeleton ArchSimGridBlock class that has such a method as well as a method that indicates whether the object is an artifact (each method has stub functionality). Finally, to make it easier for you to get started and to test your program at every step of the way, we have provided two classes, ArchSimApp and DummyArchSimulation, that will allow you to compile and "run" the other classes we have provided.

In summary, the files being provided to you are:

• ArchSimApp - the main application that starts the graphical user interface
• ArchSimGUI.java and ArchSimDisplay.java - the class that implement a graphical user interface for the archaeology dig simulation and the class that displays the grid within that user interface
• ArchSimulation - the interface that specifies the set of methods that the GUI invokes in responding to user events
• DummyArchSimulation - a trivial class that provides empty implementations for the methods specified by the ArchSimulation interface; you should leave this class as it is and create a new class that implements the ArchSimulation interface
• ArchSimGridBlock - an extension of GridObject that provides an isVisible method (actually, this class extends TextCell, so you can use it to put simple strings in the grid); you could add functionality to this class or create subclasses that have the functionality you want
• grid.jar - the Java archive library for the Grid Package, containing classes such as BoundedGrid, GridObject, TextCell, etc. Class documentation for all classes in the Grid Package can be found here.

Suggestions for Proceeding:

• The first thing you should do is to become familiar with the classes we have provided, particularly the ArchSimulation interface and ArchSimGridBlock classes.
  
• Next, you should develop a design for your simulation program that shows the existing classes and any additional classes you think you will need, what operations they should have, and how you expect them to interact. For example, you may wish to have different classes that represent the different types of blocks in the simulation, with shared behavior in a shared superclass. (In order to come up with an appropriate design, you should thoroughly understand the problem specification, so make sure you read the rest of the assignment before continuing with your design.)
  
• You may wish to begin by placing the artifacts in your grid. Remember that there should be no fewer than 5 artifacts and no more than about 10% of the number of cells in the grid. Each artifact should be placed at a random location in the grid and no two artifacts should be placed at the same place. Run the program to test it.  For testing purposes, you may want to have all your artifact blocks visible when first constructed, so that you can see where your program is putting them.
  
• For each grid location that does not contain an artifact, you should count up the number of adjacent artifacts (in other words, the number of adjacent blocks that contain an artifact). Note that the grid object that the ArchSimGUI class passes to an ArchSimulation class considers all eight adjacent locations around a grid cell (including the ones on diagonals) to be its neighbors. Thus, the number of adjacent artifacts may range from 0 to 8.  You may wish to put objects representing (and displaying) the neighboring artifact count in the grid at the very beginning, before the simulation starts, or you may wish to insert them as the user clicks on the corresponding cells.  Grid cells that have no adjacent artifacts should be visually distinctive from those that have adjacent artifacts.  Test your program so far. (Again, you probably want all objects in the grid to be visible for this testing.)
  
• Once you can place and display artifacts and can display locations that have been found to be empty (with artifact counts if there are artifacts adjacent to an empty location), then you can modify your program so that the grid appears to be empty when the simulation starts (any objects in it at the start are invisible) and the contents of the various grid blocks are made visible only when the user clicks on the corresponding cell.  Test your modified program.
  
• Modify your program to indicate that an unsuccessful grid simulation when the user clicks on (digs up and damages) an artifact.  Test your program.  If you have done this correctly, the graphical user interface should change the background color of the grid and change the window title to be an error message when the user clicks on a hidden artifact.
  
• Enhance your program to recognize a successfully completed dig. If you have done this correctly, the graphical user interface should change the background color of the grid and change the window title to be a congratulatory message when all dig site locations that do not contain artifacts have been explored.
  
• As you go, you should create javadoc documentation for your new classes and methods, and should use comments inside your methods for internal documentation.  When you are finished with your project, you should create user documentation for your program that is accessible from the "Help" menu. To do this, you will need to edit the ArchSimApp class, which creates the "Help" menu.  Provide the appropriate information for the author(s), assistance, and date.  Then create a document called ArchDigHelp.html that contains information for users about what the program is, how it works, what it does, etc.  Save this file in the same folder as the .project file.  Run the program and test both menu items in the "Help" menu.
  
• You may use any of the classes in the Grid Package (grid.jar), including
  • edu.kzoo.grid.TextCell -- a class for objects containing text that can be put in a grid.  The current ArchSimGridBlock class extends TextCell. 
  • edu.kzoo.grid.GridObject -- the more general class for objects that can be put in a grid.  TextCell extends GridObject, as does the ColorBlock class you saw in the GridPlotter project.  You may wish to change ArchSimGridBlock to extend GridObject or ColorBlock rather than TextCell if you don't want to use text strings to represent artifacts  and empty blocks.
  • edu.kzoo.grid.Location - this class is exactly the same as the class you are used to from the Marine Biology Simulation case study.
  • edu.kzoo.grid.Grid -- this class is a two-dimensional data structure you can use to simulate your simulation grid. It has some methods that should be very useful for your implementation of the simulation.
  • Documentation for all the Grid Package classes can be found online.