Before you can use GridCity, you will need to have a Java development environment installed on your machine. In this document we will provide instructions for using the Sun JDK with Windows 95 or Windows NT. If you are using a different Java development environment, these instructions may not be correct for your setup. If you do not have a Java development environment installed on your machine, you can download Sun JDK from java.sun.com. Please follow the instructions that come with the Java environment to install it or consult your local system administrator.
Once you have installed all of the necissary files, you are ready to try it out and see if it works. From the DOS prompt, use the cd command to make your GridCity directory the current one. Once you are in the correct directory, type javac *.java to compile all the code that is not already compiled. Now you are ready to run the first example. Type java Demo. GridCity should then appear, with a demo program.
When the example screen first appears, the vehicle will not move. You must click
on the "Step" or "Run" buttons above the grid to make
the instructions execute.
The "Run" button will cause the vehicle to execute instructions without stopping. The program will pause after each action instruction (ahead, turnLeft, pickup, or deliver). The delay is controllable from the "Options" menu. You may choose from 0.2 seconds to 3 seconds of delay. Clicking either "Stop" or "Step" will make the execution to pause.
The "Step" button will cause the program to execute and then stop automatically after the next action instruction (ahead, turnLeft, pickup, or deliver) is complete. You may click "Step" repeatedly to execute the entire program or click "Run" at any point.
To exit the simulator, choose "Quit" from the "File" menu.
You are now ready to begin developing your own code for use with this system.
The demo program that you just ran demonstrates the easiest way to control a vehicle, andie. When the program begins, it creates the "world" of GridCity and reads its state from a "world file." You can instruct the vehicle to move about, and when you do, you are doing simple programming. Below is the complete code for the Demo.java program you ran above:
/** * This is a small demo program * Intended to test if GridCity and the JDK are working correctly **/ public class Demo { // The World private static World theCity; // The Vehicle private static Vehicle andie; // The main method public static void main(String args[]) { // Creating a new World using the specified World file theCity = new World("Blank.gcw"); // "Creating" andie andie = theCity.getVehicle(); andie.ahead(); andie.ahead(); andie.turnLeft(); andie.turnLeft(); andie.turnLeft(); andie.ahead(); andie.ahead(); } }
Each time you write a program, the "Main" method is what will be executed. This is where the program will start. In the first few programs that you write, all of your code will be in the main method.
The first thing that you'll see in this code example is
/** * This is a small demo program * Intended to test if GridCity and the JDK are working correctly **/
public class Demo {
The next thing that you see in this code are the declaration of the Vehicle and
the World:
// The World private static World theCity; // The Vehicle private static Vehicle andie;
Next comes the main method. Again, this is the method that will execute when you run your program.
The method header for main looks like this:
// The main method public static void main(String args[]) {
The first thing that our program here does is to create a new World and Vehicle:
// Creating a new World using the specified World file theCity = new World("Blank.gcw"); // "Creating" andie andie = theCity.getVehicle();
Next come the actual command that we are giving andie:
andie.ahead(); andie.ahead(); andie.turnLeft(); andie.turnLeft(); andie.turnLeft(); andie.ahead(); andie.ahead();
The only thing left in the program is:
} }
GridCity comes with a package of graphics including alternate backgrounds, walls, vehicles, and parcels. To view the images, go here.
There are two basic ways to change the graphics in GridCity. The first option is to do this through putting the graphics for that background and walls into the world file. To do this, please read the next section on Making World Files.
The second option is to code the graphics in your program. There are methods provided to make changes to the background and wall images in GridCity, as well as setting the images for any new vehicles and/or parcels that you create.
To change the background graphics there are currently two methods. Both of
these methods are to be called on the world. There is also a method to change
the graphics that appear as walls. So, using our previous example, but using a
different world file, and giving the program a different name, I will change
the background, then change the wall images. I will then change the background
without refreshing. This will only change the background image for a corner as
a vehicle enters it. This is useful in programs that would do things like solve
a maze, so you can see if there is any area of the world where the vehicle never
goes.
/** * This is a small demo program * Intended to test if GridCity and the JDK are working correctly **/ public class GraphicsDemo { // The World private static World theCity; // The Vehicle private static Vehicle andie; // The main method public static void main(String args[]) { // Creating a new World using the specified World file theCity = new World("graphicsExample.gcw"); // "Creating" andie andie = theCity.getVehicle(); theCity.setBackground("Ocean.gif"); theCity.setWall("LifePreserver.gif"); theCity.setBackgroundNoRefresh("Space.gif"); andie.ahead(); andie.ahead(); andie.turnLeft(); andie.turnLeft(); andie.turnLeft(); andie.ahead(); andie.ahead(); } }
You'll notice that you cannot see the vehicle in the picture. This is because the vehicle still has the default image. To change this, we will have to create a new type of vehicle. Creating a new type of vehicle is done by writing a class that extends the Vehicle class. Within this class's constructor, you can set it's image to be different from the default. Let's create a boat:
public class LittleBoat extends UltimateVehicle { public LittleBoat() { setAttribute("imageName", "boat"); } }
Now that we have created a boat let's use it in our program:
/** * This is a small demo program * Intended to test if GridCity and the JDK are working correctly **/ public class GraphicsDemo2 { // The World private static World theCity; // The Vehicle private static Vehicle andie; // The main method public static void main(String args[]) { // Creating a new World using the specified World file theCity = new World("graphicsExample.gcw"); // "Creating" andie andie = new LittleBoat(); // Now that andie is not a plain Vehicle, we must replace him theCity.replaceVehicle(andie); theCity.setBackground("Ocean.gif"); theCity.setWall("LifePreserver.gif"); theCity.setBackgroundNoRefresh("Space.gif"); andie.ahead(); andie.ahead(); andie.turnLeft(); andie.turnLeft(); andie.turnLeft(); andie.ahead(); andie.ahead(); } }
->LittleBoat.java The gcw file from this example -> graphicsExample.gcw
To change the images for parcels, you do almost the same thing as you did for the vehicle. You create a new parcel class. Let's say that we want all of the parcels to be boxes:
public class Box extends Parcel { public Box() { setAttribute("imageName", "blueBox.gif"); } }
/** * This is a small demo program * Intended to test if GridCity and the JDK are working correctly **/ public class GraphicsDemo3 { // The World private static World theCity; // The Vehicle private static Vehicle andie; // The main method public static void main(String args[]) { // Creating a new World using the specified World file theCity = new World("graphicsExample2.gcw"); // "Creating" andie andie = new LittleBoat(); // Now that andie is not a plain Vehicle, we must replace him theCity.replaceVehicle(andie); theCity.setBackground("Ocean.gif"); theCity.setWall("LifePreserver.gif"); theCity.setBackgroundNoRefresh("Space.gif"); andie.ahead(); andie.ahead(); andie.turnLeft(); andie.turnLeft(); andie.turnLeft(); andie.ahead(); andie.ahead(); } }
->LittleBoat.java
->Box.java The gcw file from this example -> graphicsExample2.gcw
There are Many classes in the simulator, however not all of these are intended to be generally used. Here is a list of all of the classes :
All of the classes include JavaDoc compatible comments which may be consulted if more information about a class is sought.
Contact info, Sharing files, Getting help -- what goes here?