Developer Area

Robocraft Software

Table of Contents

Overview

This year's robocraft software was especially designed to help you develop and debug your player classes. Notably, we have separated the Game Server from the Game Client. Here is a description of these two parts of the software:

GameServer: There is only one implementation of the GameServer module, and it includes the RoboVM and the game engine that runs the Robocraft world, as described by the specifications.

GameClient: GameClients receive events from a GameServer while it is running a robocraft match. We have provided two such clients: a text client and a GUI client. The text client listens to GameServer events and prints them out in the terminal. The GUI client allows you to interactively watch, rewind, and step through a robocraft match.

The GameClient and GameServer communicate via TCP/IP, so they can be running on entirely different computers. If, for example, you have a computer with a fast CPU but a slow GPU, and another with a slow CPU but fast GPU, you could run the GameServer on the former and the GUI GameClient on the latter to maximally utilize your computing resources.

System Requirements

Software. The following operating systems are supported:

Hardware. The robocraft software requires at least one fairly fast computer with an OpenGL-accelerated graphics card and a decent amount of RAM. It is hard to quantify exactly what is required, because every robocraft match is different. However, we can give you the following rough guidelines:

The default software configuration is to run the GameClient and GameServer on the same computer. For this, we recommend a 1ghz CPU and an OpenGL-accelerated graphics card with at least 32 megabytes of VRAM (video RAM). Additionally, long matches that involve many robots could consume several hunded megabytes of RAM in the Java VM. We recommend having 512MB on your system to be safe.

If you run the GameServer on a separate computer, the GameServer itself takes up little RAM, a lot of CPU, and of course no VRAM. The TextClient provides a very simple interface to the GameServer, and has low system requirements as well.

Known Good Platforms: Known Bad Platforms: If you are used to working on athena-linux machines, we suggest trying SunBlades. There are a lot of SunBlade 100 athena machines on campus. In our experience, once you get past the capslock/control key placement, and learn to prefix some of your commands with "g" (ggrep, gmake, gtar, etc.), they are a workable development platform for linux users.

Finally, if you are experiencing performance issues with the software, please try out different combinations of the configurable properties, some of which cause the software to use less RAM or VRAM.

Download

The latest version of the software is:

robocraft-2.3.1.tar.gz   [Released 2005-01-25 @08:30pm EST]

Running the Software

These instructions assume you are on a UNIX-like system. If you are on windows, we suggest you download cygwin from http://www.cygwin.com/. You also need JDK 1.4.2 from Sun. We assume you have basic knowledge of how to get java programs running on your system.

Before you do anything, you will need to download the software by clicking on the above link, and unpack the file with the following command (where <version> is replaced by the version number of the software you have downloaded):

$ gtar xzvf robocraft-<version>.tar.gz

Next, if all goes well, you should be able to run an example match by typing:

$ cd robocraft-<version>/
$ ./run-robocraft

This script will try to detect your system type and configure your CLASSPATH and native library paths to use the appropriate OpenGL native library for your machine. It will also respect your existing CLASSPATH environment variable, so you can put your compiled player classes in there. Note: If you run the GameServer on a separate computer, your compiled player classes need to be in the CLASSPATH of the server, but not necessarily the client. The server is the module that runs your players, even though the GUI client tells the server which players to run.

Using run-robocraft with no arguments will launch the GUI GameClient, which will allow you to start a local GameServer or connect to a remote one. To run the text client instead of GUI client, use the "-textclient" switch and appropriate properties (see Appendix A). For example:

$ ./run-robocraft -textclient -Drobocraft.hostname=myserver.mit.edu

To run the GameServer only, use the "-gameserver" option, which will start a gameserver listening on a specified port. For example:

$ ./run-robocraft -gameserver -Drobocraft.port=6370

Using the GUI

The GUI GameClient is mostly intuitive, but here are some features we would like to bring to your attention:

Known Issues

Slow Framerate: If your system does not have hardware support for OpenGL graphics, it will most likely emulate the OpenGL commands in software. If this happens, you will not get any error messages, but will experience dismal graphics performance. To determine whether this is happening to you, check the messages that are printed on the screen when you run the GUI client. You should see lines similar to the following:

GL_VENDOR: ATI Technologies Inc.
GL_RENDERER: ATI Radeon 9600 XT OpenGL Engine
GL_VERSION: 1.5 ATI-1.3.36

If you see anything like "ForceSW" or "Software Emulation" then you do not have hardware OpenGL support, or your drivers are not configured properly. See Appendix B for tips on getting OpenGL running.

Another thing that can cause slow framerate is when your graphics card cannot hold all of the robocraft textures in video memory. To see if this is affecting you, try resizing the Robocraft window until the map area is small. If the performance improves all of the sudden, it means that you do not have enough VRAM to hold the match at full size. You could then try re-running the match with the -Drobocraft.lowResTerrain=true option.

Gray Screen (no graphics): Some implementations of OpenGL refuse to draw anything when they cannot use hardware acceleration. If you see a Robocraft window with nothing drawn in it, there may be a problem with your OpenGL hardware setup (such as too little VRAM). Try the suggestions in Appendix B.

MatchServer delay on Windows XP SP2: Sometimes when you start a new match on Windows XP SP2, there is a 2-6 second delay before anything happens. We believe this is related to the XP firewall.

Appendix A: Configurable System Properties

The following properties can be configured when running the robocraft client by specifying "-Dproperty=value" when using the run-robocraft switch (see examples above).

Property NameDescriptionDefault Value
Connection
robocraft.serverHost Hostname of remote server to connect to. localhost
robocraft.serverPort TCP port of remote server to connect to (or port to listen on if running in "-server" mode) . 6370
robocraft.synchronousIO Don't use a separate thread for IO on the Game Server. false
Match
robocraft.teamA Class name of TeamA's RobotPlayer  
robocraft.teamB Class name of TeamB's RobotPlayer  
robocraft.map Map name to use (located in GameServer classpath)  
robocraft.autorun Tells the GUI client to start running the match immediately false
Graphics
robocraft.maxFPS The maximum number of frames drawn per second. On a fast machine, frames will be drawn at regular intervals with approximately this rate. 60
robocraft.printFPS When enabled, print a measurement of the current frame-rate to the terminal every 3 seconds. false
robocraft.roundsPerFrame The number of rounds to advance the GUI between frames. This rate is independent of the GameServer. The rate of playback in the GUI is reduced when the GameServer does not make rounds available fast enough. 1.0
robocraft.lowResTerrain Causes a lower-resolution texture to be used to draw the terrain. false
robocraft.smallWindow Causes the graphics during a match to be shown in an initially small window. false
robocraft.disableEnergonBars Hides the energon level indicators for all robots. false
robocraft.disableAudio Disables all audio effects. false
RoboVM
robocraft.silenceA Whether to silence System.out and System.err for Team A false
robocraft.silenceB Whether to silence System.out and System.err for Team B false
robocraft.debugMethodsEnabled Whether to execute "debug_" methods false

Appendix B: OpenGL Tips

If you are having problems with the OpenGL graphics, here are some things to try:

Appendix C: Submitting Bug Reports

If you think there is a problem with the Robocraft software, please send an email to the 6.370 organizers. Make sure to include all of the following: