CS30 -- Introduction to Computer Science II
Fall, 2004
Project 3
(updated 11/23/2004)

Programming Project:
This week, you will continue the general puzzle framework we have been developing.  However, you will be creating a new program that will interact with the program you've been developing.  In summary, you will implement a network communication scheme and develop a user-interface for an agent.  Get started right away.

To clarify, this portion of the project should be able to load a grid initialization file as specified in the last project.  However, the file will not contain any monsters.  Thus, your program only needs to consider a single agent controlled through the user-interface you will develop.  Since you'll only have a single agent, you can have the Grid wait for input from the user-interface.  Of course, in the future we will not have this simplification.

1. Network Communication Scheme.  For this part of the project, you will write a class that wraps the socket communication capabilities demonstrated in the TestClient.java program.  (Here is the code for TestClient.java and TestServer.java).  Please call this class, GridClient.  This class will be distinct from the program you've been writing up to this point.  The primary public methods you will need to provide are:
This class will serve as the communication interface between client programs and the Grid world.  To accomplish this, it will receive messages from the Grid world with sensory information, and it will send messages to the Grid world with actions to perform.  Controllers that have logic to determine what action should be selected next will use an instance of the GridClient to get the information it needs to make an informed decision and then to send the desired action to the Grid world.  The communication in both directions will take place over network sockets.  Fortunately, Java provides the Socket and ServerSocket classes that you will use to establish your communication link.  You can find information in the standard Java documentation, and this tutorial may be quite helpful.

The communication link will be passing information in two directions.  You will be using the GridClient object (used by a controller) to send commands to the Grid object (the world simulator).  The protocol we will use for now is: 'f' for moveForward(), 'b' for moveBackward(), 'r' for turnRight(), 'l' for turnLeft(), 'g' for grab(), 'd' for drop(), and 'u' for use().  Since the Grid world (acting as the server), will have Socket instances for any agent controller (although to start it will be a single agent), it can keep track of which agent is performing which action.

The GridClient class must also receive data from the Grid world.  For this week, it will just receive the direction to the food.  This will be given as one of the characters: 'f', 'b', 'r', 'l', and 'h' for forward, back, right, left, and here as the current direction of the food (or location in the case of 'here').  Thus, the Grid object will compute the appropriate character to send based on the agent's current heading and the location of the food.

At this stage as a group, it is important that we converge on the command characters we will pass over the network and we might as well settle on agent method names as well.  Please use the ones I've given above (moveForward(), etc.) in your Grid or GridObject classes (or subclasses) where appropriate.

[This paragraph describes where you're headed but is not required for project 3.]  Finally, you should structure the communication so that the Grid world processes agent actions in turn.  You'll probably want a collection of objects that contain an agent GridObject and a socket that communicates with an agent controller.  After the Grid world processes all the agent actions, then it finalizes any updates to the world that are necessary and sends the sensory information (initially just smell-sense direction to food) back to the agent controllers.  Then repeats, processing agent actions, etc.

Although we will eventually have multiple agents communicating over multiple sockets and you should employ collection ADTs that will support that, for now you can assume a single agent connection.

Finally, it is important to note that communication is a two-way street, and we need to provide something on the other end of the line with which the GridClient may interact.  You can directly incorporate the Socket and ServerSocket features found in the TestServer.java program into the Grid class.  The benefit of have the GridClient class is that the UI (below) and future agent controllers can easily incorporate an instance and use it to communicate with the Grid.  Since the Grid is essentially unique, we can include a socket as a private data field and appropriate calls can take place where they are needed.

2.  A User-Interface.  A network communication scheme is useless without a program to use it.  In this part of the project, you will write a new program that uses a GridClient object as a means to control an agent in your Grid world.  You need to create a user interface that enables a human to control a particular GridObject agent.  In other words, a person can interact with the Grid world through the user interface and move an agent around, have it pick up tools, break rocks, etc. so that it can pick up the food and eat it.  Hint: you might want to use the GridClient as a component.

This week, the user interface should simply be a character-based interaction at a terminal window.  It will consist of a "read, send, receive, print" loop in which the user enters a desired action, the user interface sends the command to the grid, the grid processes the action request and then sends the new direction to the food back to the user interface, which finally prints the new direction and then waits for the user's next action.  You can follow the progress of the controlled agent on the Grid display that you have already implemented.

Your interface must support the seven basic actions you have already implemented.  They are: moveForward(), moveBackward(), turnRight(), turnLeft(), grab(), drop(), and use().  I suggest that you let the user type the characters: f, b, r, l, g, d, and u for these actions, respectively.  You should (at a minimum) print the sensed direction to the food and then prompt for the next command input.  Read the command and send it to the Grid world using the network interface above.  (The human, together with the user interface, is taking the place of the agent controller.)  You will also want to provide a help option that displays the available actions.  This should loop either endlessly or until the user quits or the agent dies.

Submission Instructions:
On your machine where you are doing your homework, create a folder called <your email name> followed by "P3".  For example, someone with email address "cjones" would create a folder called "cjonesP3".  Inside that folder, place plain text file(s) containing your answers to any exercises.  Also, place whatever Java files are necessary for your Programming Projects in the same folder.  Finally, either tar or zip the folder so that when I extract it, the folder "<emailname>P3" will be createdIf you choose to use zip instead of tar, change the extension of the resulting zip file from "<something>.zip" to "<something>.foo".  This way, our webmail will allow you to attach the file.  If I get an attachment with extension .foo, I will change it back to .zip and all should be well.