Karel J. Robot
Premier Version

(July 2004)

Get the zip file and unzip it

The current version of the Karel J Robot Simulator (click at left to go to download page) is available. The zip now contains the Simulator User's Guide and a set of world files keyed to the figures in the book. The new version scales the robot images as you change the size of the window. There are a few other enhancements. See the User's Guide.

Here is a complete Simulator User Guide in pdf format.

If you have an older version of the jar file, don't forget to remove it. Some errors have been caused by having Java find the old version instead of the new.

You should get the following files all in a new directory. Keep them together and make this your working directory.

• KarelJRobot.jar
• karele.gif
• kareln.gif
• karels.gif
• karelw.gif
• kareleOff.gif
• karelnOff.gif
• karelsOff.gif
• karelwOff.gif
• test.kwld <- a sample world file. It is text
• KarelMain.java <- a sample "main" that you can use to test your instalation.
• testInfected subdirectory with KJRTest.jar and sample files.

On many systems you won't actually need the .gif files. The Macintosh under System 9.x does seem to need them, however.

There is also a Windows subdirectory and a Macintosh Folder. These contain system specific files that should be put with the files above on your system. The Mac files are for OS 9 only. They are not needed in OS X. (Note. I use OS 9. The materials here should work on earlier versions if you have Java running on your system.)

If you download this (see the link above), I'd like to know about it so I can keep track of how many users there might be. Since I don't track your usage here, the only way I can know is if you send me email. Please do, at berginf@pace.edu.

If you are an instructor, you may distribute these materials to your students for use with the manuscript. If you are a student, you may download a copy for your own use.

If you are a student, I won't be able to help you with assignments from your instructor. Sorry. If you need help, ask your instructor after you think really hard about the problem.

Note that everything here is an extension of the original simulator described at http://csis.pace.edu/~bergin/KarelJava2ed/kareloptions.html, though that is now obsolete as this is much better. The instructions apply, however.

Change History

On October 3, 2003, I started a Change History for the simulator

Running Karel J. Robot

Write a main class something like KarelMain.java here. Make sure that the class is in package kareltherobot. You should probably implement the Directions interface also.

Run it, including the jar file KarelJRobot.jar in your classpath

   java -cp .;KarelJRobot.jar kareltherobot.KarelMain

If you use an IDE to develop, make sure you include the jar file and (depending on your IDE) get it into the classpath also. On the Macintosh prior to OS X you will need to use something like Codewarrior.

The above command is for Windows, of course. On Unix or on the Macintosh (under OS X using a Terminal window) replace the semicolon above with a colon.

IMPORTANT New Information. The Karel world is no longer visible by default. you need to execute the command World.setVisible(true); from your code. I suggest that you do this from a static initializer in your main class file.

static
{	World.setVisible(true);
}

In fact, this is also a good place from which to open a world file. If you do it before settiing the world to be visible, your world will first appear with all walls and beepers in place.

How to build a world.

Run the WorldBuilder in the jar file itself.

   java -cp KarelJRobot.jar kareltherobot.WorldBuilder

On many systems, double clicking on the KarelJRobot.jar file should launch the world builder. See Caveats (below) for an assist in doing something similar on systems that don't support this.

Pick up a tool in the tools (button) panel. The name of the current tool is highlited.
Click where you want to place an item controlled by that tool.

For beepers click near an intersection when using the beeper tool.
For walls, click across streets (for vertical walls) and across avenues (for horizontal walls) when using the corresponding tool.

To put more than one beeper on a corner, click more than once with the beeper tool active.
To lower the number of beepers on a corner, control click the corner with the beeper tool.

To put an infinite number of beepers on a corner, control-click (with the beeper tool) when there are none on the corner.

To clear all the beepers from a corner, shift-click the corner when using the beeper tool.

To remove a wall from across a street, control click the wall segment with the appropriate wall tool.

To change the number of streets or avenues in the world, enter an integer into the corresponding text field and hit enter. Note that this doesn't restrict the world in any way. It just determines how much of it is drawn with street and avenues.

Save when you like. I've used an extension kwld here, but there is nothing special about it. It is neither assumed or automatically appended.

You can also open an existing world to edit/modify it.

The Clear World button will remove all elements from the world. (Be careful, there is no UNDO here.)

Quit the world builder by closing either of its windows. If your world has been modified since the last Save you will be prompted to save it again. Note that if you QUIT using a menu or command key, this extra Save prompt will NOT occur.

If you use an IDE, make a separate project for this and include the jar file. Make kareltherobot.WorldBuilder the main file for the project. In Codewarrior (on the Macintosh at least) you need to set the output to be a class folder rather than a jar file, since the main is in the existing jar file, and not in any code of your own. After you build this class folder will be empty.

Here is the World Builder running on a Macintosh (OSX). the look is similar on other platforms. Since it is written in Java 1.1, it uses the look and feel of your platform.

World builder shows the position of the mouse in street,avenue coordinates if you have selected any tool. If the current tool is the Beeper tool, it shows the nearest corner (where the beeper will be placed if you click). If the current tool is the Horizontal Wall tool, it shows where the corner below the wall that will be placed. If the current tool is the Vertical Wall tool it shows the corner to the left of the wall that will be placed.

(NEW) Here is a complete set of worlds for the book -- zip format with dos endlines.

How to use a world created with the world builder.

Remember the name you used when you saved it. Say test.kwld.

Include a statement in your robot program to open it. Include this at the beginning of
your main task block.

 World.readWorld("test.kwld");

The world file will be opened and its content merged into your existing world.

Note on the files created by the world builder.

The format is compatible with that of the older simulator. However, there is no need to use the older version as this is an extension.

You can actually write the world files with a text editor.

Lines that do not start with a keyword for the builder are ignored. Elements can appear in any order. They are NOT case sensitive.

Here is a sample file.

KarelWorld
Streets 10
Avenues 20
beepers 3 4 1
beepers 4 2 1
eastwestwalls 3 2 4
northsouthwalls 4 2 2
northsouthwalls 4 3 3
northsouthwalls 1 5 5
northsouthwalls 1 4 4

The first line (KarelWorld) is not a keyword, but it might be in the future. It might also contain a version number eventually. It is ignored when reading now, but written when you save a world. The following gives the meaning of the current keywords. This is not expected to change.

• Streets --The number of streets to draw.
• Avenues --The number of avenues to draw.
• beepers --The data is: street, avenue, number of beepers, without punctuation of any kind.
• eastwestwalls -- The data is: North of Street, first avenue crossed, last avenue crossed. Last should be bigger than first (or equal).
• northsouthwalls -- The data is: East of Avenue, first street crossed, last street crossed. Last should be bigger than first (or equal).

The world builder writes out a separate wall command for each segment of a wall (one block long). If you do it by hand, you can combine them.

If you create a world in a Robot program using the programming interface (in this version or the previous one) and save it, it will be consistent with the world builder files.

How to use this environment in your Robot programs.

Turn this page to see additional instructions.

Instructions for some World features, how to use a task, and running robots in threads. See the JavaDoc for more on World capabilities. The JavaDoc files are now in the distribution.

Compiling Your Own Robot Programs

If you don't have the benefit of an IDE and need to compile your programs from the command line, you need to do two things generally. First is that you need the -d . option (dash d space period). Second you need the -classpath option. Probably it should be (for Windows) -classpath .;KarelJRobot.jar. So your full command would be

javac -d . -classpath .;KarelJRobot.jar SuperDuperSteepleChaser.java

for example. It is case sensitive. On unix systems the single semicolon should be replaced by a colon.

Caveats

Known bugs:

In the world builder: On the Macintosh OS 9 there is a drawing update bug. If the main window gets out of sync, just resize it. On OS X, if you quit this version with Command-Q or by selectiing Quit from the Apple menu, you won't get the save menu for a changed file that you would if you click the close box for one of the windows. The same seems to be true of a double clickable jar (on OS X, for example)

In the world builder, the control dialog for the simulator (which is useless here) isn't always hidden. The effect is sporadic.

OTHERWISE:

It seems to work on a PC. If you work on a PC double clicking on the KarelJRobot.jar file may not run the world builder. If not, there is a batch file that you can use to do this. Put it in the same directory as the jar file and double click it to run the world builder. This file is in the distribution zip in a Windows directory. If you have trouble, create a file named WorldBuilder.bat with contents (just one line): java -jar KarelJRobot.jar

I haven't tried it under Linux.

It is written in Java 1.1 so it runs on Mac OS 9. The button highliting doesn't happen though. If you work on a Macintosh under OS 9, there is an application shell for the world builder. It is in the Macintosh folder in the distribution zip. Put it in the same folder as the KarelJRobot.jar file.

The Macintosh (OS 9) world builder application shell and the Windows batch file mentioned just above are now in the zip in separate folders. Move the file appropriate to your system to your working directory (the one that contains KarelJRobot.jar) for use. You can then just double click to run the world builder. On Mac OS X, double clicking the jar itself should work. It may also on Linux, but I have no way to test it.

Recent Features, not shown above:

The simulator now shows the mouse's position in the main window as the closest corner. The coordinates are in the control dialog. Note that (as before) the control dialog has a close box, but it is inactive. The dialog may be resized, however, for fine grained speed control.

Robots are now shown slightly differently after they turnOff. They have a greyed out look.

There are two new messages understood by UrRobots and hence by all robots. You can make a robot invisible (at the next drawing of the screen) by sending it a message like

karel.setVisible(false);

You can make it visible again with setVisible(true). You can also ask an UrRobot if it is currently visible with the predicate isVisible( ). Note that these are intended for advanced use and are not part of the regular programming model of robots, nor will they be described in the book/manuscript. Note especially that predicates are only introduced for Robots (Chapter 5) in the text. These new instructions are useful, however, if you have a lot of robots, only some of which are of interest at a given moment, or if you want to remove robots from the screen after they turnOff. Thanks to Don Slater of Carnegie-Mellon for suggesting this.

NOTES

Even though it is one code base there are really two applications here. The world builder is separate from the simulator. You can run them at the same time, however. You can even keep the world builder open as you run your Robot programs in the simulator. You will need to save the world in the world builder using a name known to the Robot program to do this effectively, however. The Robot program only gets a new copy of the world when it executes readWorld. Note that readWorld will merge the contents of the file into the existing world, not replace it.

Java Doc

Here are the Java doc files for this simulator.

If you would like the Java Doc files on your own machine rather than this one, download KJRdocs.zip and unzip it in a convenient place. Use your browser to open the index file.

Robot Runner

I started out to build a world builder, but got carried away. The simulator part has a new feature that you can use if you like, though you don't need to. You can still put robot commands and world building commands into a Java main and it will work. However, in looking for something simpler for students to use, I included the following:

Build a new class that is in the kareltherobot package and implements the RobotTask interface. (This extends Directions, so you don't need to implement both). Give this new class a method with protocol public void task(). Put all of your robot commands and any world commands inside this task method. Here is an example:

package kareltherobot;

class Test1	implements  RobotTask
{
	public void task() 
	{
		World.readWorld("box.kwld");
		UrRobot karel = new UrRobot(3, 3, East, infinity);
		
		karel.turnLeft();
		karel.move();
		karel.turnLeft();
		karel.move();
		karel.turnLeft();
		karel.move();
		karel.turnOff();	
	}
}

The RobotTask interface requires only this one method.

Now, build a project that includes the above file and the KarelJRobot.jar file (and the .gif files if necessary).

Now run your program with any of the following commands:

java -cp .;KarelJRobot.jar kareltherobot.KarelRunner kareltherobot.Test1

or

java -cp .;KarelJRobot.jar kareltherobot.KarelRunner Test1

(the package will be assumed in the above case) or even just:

java -cp .;KarelJRobot.jar kareltherobot.KarelRunner

In the last case, you will be prompted for the name of the class and you can respond with either Test1 or kareltherobot.Test1. This assumes you have put your classes into package kareltherobot, which you should do in any case.

For each of these the task will be run AND you will be prompted at the end to ask if you want to run it again without restarting. Any response that does not begin with the letter 'n' (or 'N') will be treated as a yes--even just a return. Before it runs again the world will be automatically cleared and the task then re-executed, including any world setup commands. There are two sample such test programs packaged in the distribution zip.

Note that on the Macintosh there is no command line normally, so the last form of the run is equivalent to double clicking on the application that your IDE (Codewarrior, for example) creates. Make kareltherobot.KarelRunner your main class, of course if you use ANY IDE on the Mac or otherwise.

Also, if you run a task in which all robots run in separate threads, the prompt for rerun will come immediately after the robots are created. This can be a little disconcerting, as the task hasn't run yet and you are being asked to run it again. Eventually the robots will complete and your response to this prompt will have effect.

NOTE: March 15, 2003. KarelRunner was called KarelTest until recently. RobotTask was previously called RobotTester. This is a change for naming consistency with other items (see below). Also note that a RobotTask class should not also extend a robot class. These task classes only work if they have a no-argument constructor available and usually robot classes do not have such a constructor. RobotTasks are to exercise robot classes, not to BE robots. For example the RobotTask above (class Test1) exercises UrRobots.

Street and Avenue Numbers

The simulator now shows street and avenue numbers if you have up to 50 streets. If you have a small screen, this will be effective only for smaller numbers, however. (Added Aug. 27, 2002)

JUnit (Test Infected) Testing Framework

Karel J. Robot now comes with a testing framework based on JUnit. It permits test first programming. You can learn more about this idea and how to use it on the Test Infected Programming page.

There is a new (June, 2004) way to give executable specificiations of Karel J Robot programs for student exercises and to exercise and test programs as they are written. It is called KarelFixture and it integrates into the Fit/Fitnesse acceptance testing structure used in Extreme Programming.

Here is what a specification for the StairClimber task looks like in this system:

It is important to note that this is an executable specification. You execute it by pushing a test button on the page that contains it (not here, visit the link above). When you test it with a correct program you get something like:

kareltherobot.KarelFixture
kareltherobot.StairClimber
Tester	kareltherobot.KJRTest	local
World	reset
Read World	stairworld.kwld
Create	karel	1	1	East	0
Message	karel	getBeeper
Assert	BeepersInWorld	0
Assert	BeepersInBeeperBag	karel
Assert	FacingEast	karel
Assert	NotRunning	karel
Assert	At	karel	4	4

The green cells indicate that the executions were successful and/or that the assertions succeeded. If the program had been incorrect some cells would show up in red with additional information about what went wrong. Visit the link for many examples and a tutorial on the usage.

Having It All

You can actually have a simulation and a world builder simultaneously running. If you use KarelRunner as your main and give NO argument (class name) you will be prompted for the class name and also to learn if you want the world builder dialog. The default is yes. If you give the class name this prompt will not appear, but you can give an additional argument following the class name, just a "w" (either case) to get the world dialog. On the Macintosh (OS 9), you will be prompted for both.

If you run your robot programs in your own main, you can also get a world builder dialog. Just call

new WorldBuilder (true);

to keep the speed/resume dialog open or

new WorldBuilder(false);

to have it closed when you run.

You can save the result of the call in a variable if you like, though it probably isn't necessary. It may be necessary in case the garbage collector tries to grab the created world builder, actually.

In fact, since the world builder and the simulation run in different threads, you can interact with the running robot program through the world builder. I suppose you could write a version of space invaders using this idea.

Now Applet Friendly

A few additional changes were made to the jar file to make Karel J. Robot usable in an Applet. The problem previously was that the worlds were read from and written to files and Applets usually can't do that. However, you can now load a world from a String (and retrieve a String version also) so that you can now build a world textually in a TextArea (for example), by copying the contents of a file and then pasting them into the TextArea. You can go the other direction as well and thus save worlds created by a world builder in an Applet.

The NEXT PAGE will show it to you in action if you have Java activated in your browser. You can see the applet code here: KarelApplet.java.

The World will be in a floating window. Don't forget to look under it for the applet.

As a special treat, here is dining philosphers running in an applet.

Note that in writing these demo applets, I wasn't careful to consider leaving and returning to a page, so it won't work properly. You may even need to restart your browser to return to a page you have left or if you have specifically closed one of the windows.

This has been tested on several systems: Netscape 6.2.2 on Windows 2000 and Macintosh OS X, Mozilla 1.0 on Macintosh OS X and OS 9.2, InternetExplorerer 5 on Windows 2000, Windows 98, and Macintosh OS X, Netscape 4.79 on Macintosh 9.2.2 (with the current MRJ and the plugin from Mozilla) and Netscape 4.78 on Winddows NT4. It seems to NOT work on Netscape 4.75 on Windows 98, however. If you try it on other systems/browsers, please let me know the results. Some problems might be bugs and some might just be incompatibilities. It is written in Java 1.1 so many older systems should work. (Note that the latest version seems to be having trouble on Netscape 4.xx. on most systems.) A user tells me that the simulator works fine with Red Hat Linux.

Using Karel J. Robot with Various IDEs

There are a lot of different system and IDE combinations used with Karel J. Robot. Here is a page of instructions that may get you started with some of them.

There was also talk at SIGCSE 2002 about putting Karel J. Robot on the Codewarrior distribution disk with special stationery to make it easy to use there.

Back to the main Karel J. Robot page.

Last Updated:June 3, 2006