Table of Contents
- System Requirements
- Running the Software
- Using the GUI
- Known Issues
- Appendix A: System Properties
- Appendix B: OpenGL Tips
- Appendix C: Submitting Bug Reports
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 RequirementsSoftware. The following operating systems are supported:
- MacOS X 10.3 or later
- Linux with XFree86-DRI and OpenGL hardware acceleration
- Windows 2k/XP with OpenGL hardware acceleration
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:
- All Macintosh computers with 32MB of VRAM and OSX 10.3 or later.
- SunBlade Athena machines. (SunBlade 1500's, the newer-looking Athena Sun machines with LCD monitors, run the software especially well).
- Windows 2000/XP with OpenGL-accelerated graphics card and proper drivers installed. See Appendix B for tips and tricks for getting OpenGL to work on various platforms.
- Linux machines with XFree86-DRI extensions and NVidia graphics card & drivers.
- Athena-linux machines do not seem to have the proper XFree86-DRI extensions that are required to run our GUI GameClient.
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.
The latest version of the software is:
Please see the ChangeLog for information on what has changed over different releases.
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):
Next, if all goes well, you should be able to run an example match by typing:
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.
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
To run the GameServer only, use the "-gameserver" option, which will start a gameserver listening on a specified port. For example:
Using the GUI
The GUI GameClient is mostly intuitive, but here are some features we would like to bring to your attention:
- You can resize the window
- The status bar at the bottom of the window indicates how much of the match has been received from the GameServer. You can click on any part of the gray area to jump to the view of that round.
- You can use the [stop]/[step forward]/[step backward] buttons to step through the rounds individually.
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
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 "
run-robocraft switch (see examples above).
|Property Name||Description||Default Value|
|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.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|
|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.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 "
Appendix B: OpenGL Tips
If you are having problems with the OpenGL graphics, here are some things to try:
- Lower your screen's resolution and pixel depth. This frees up more video memory for OpenGL.
- Install the latest drivers for your video card.
- (Windows or Mac): Try out the OpenGL Extensions Viewer software. This program will give you lots of useful information about your setup, such as how much VRAM your graphics card has. Make sure you can render all the test animations at a high framerate.
- Use the
- Use the
Appendix C: Submitting Bug Reports
If you think there is a problem with the Robocraft software, please send an email to . Make sure to include all of the following:
- The exact command you used to run the software, including any optional properties
- Any player code necessary to reproduce the error
- Steps to reproduce bug (if reproducable)
- Screenshot (if graphics-related drawing problem)
- All console output generated by the robocraft software.
- Important: If the software is a "freeze" bug (something
just stops working), make sure send us a thread dump. On a
UNIX system, you can generate a thread dump by sending a QUIT signal
to the java process. (i.e., type where 12345 is the process ID of java, obtainable by using the
"kill -QUIT 12345"command). On windows, type "Control-BREAK" in the console window running java.