The BattleCode software consists of three major components:
The BattleCode software requires:
The following hardware is recommended for best performance:
Ensure that you have the correct version of the Java VM and compiler installed on your machine. You can do this at a command prompt with:
javac -version java -version
Apache Ant is a Java-based build system similar in theory to UNIX make. This year, we are providing an Ant build file to conveniently compile players and run the BattleCode software.
If you are using the BattleCode installer, you have the option of including Ant in your BattleCode installation. If you already have Ant set up on your system, you don't need to include it in the installation.
You are not required to use the Ant build script, though it's been designed so that you can get up and running quickly and easily.
java -jar [file] on other systems).
cmd, then hitting OK. OS X users can run Terminal.app in Applications/Utilities.)
ant run (for Windows users, and non-Windows users who already have ant) or ./ant.sh run (for everyone else).
To install the BattleCode software, download the installer and execute it. On Windows systems, this is usually accomplished by double-clicking the downloaded jar file. On other systems, you can run java -jar battlecode-[version].jar at a prompt. The installer will guide you through the software setup.
Since you'll probably be working in installation directory, you should install BattleCode to a user-writable location (i.e. ~/BattleCode or in /My Documents, but not in /usr/local).
If you are working from Athena, note that there is no special setup for Athena machines; you can follow these instructions exactly, except that you must first "add java" before executing the installer and "add sipb" to use Apache Ant.
The installer is also capable of updating an existing BattleCode installation to a newer version. To perform an update, run the installer, choose the directory of the existing installation, and confirm that you'd like to overwrite the target directory.
Note that if you have an active Internet connection when running the BattleCode software, it will automatically notify you when a newer version of the software is available. The first time it detects a new version, a pop-up dialog appears when the software is started; each subsequent start shows an exclamation icon in the lower-left hand corner of the match dialog.
If you'd rather not use the installer program, we provide a jar archive of the distribution that you can simply extract. (This is similar to how the software was installed in previous years.) However, if you choose to do this, you'll have to manually update your installation as new versions are released.
The included Ant script allows you to compile your player and prepare it for submission without having to worry about the Java classpath and other settings. To take advantage of this, simply place the source code for your player(s) in a subdirectory of teams folder in your BattleCode installation directory.
For instance, if you are team #1, you'd have a folder called team001 in your teams folder, and in team001 you'd have RobotPlayer.java, etc.
After you've placed your source code there, navigate to the installation directory and run:
ant build
This command will invoke the Java compiler on all source code in the teams folder.
After you have installed the software, open Eclipse and choose "File" -> "New" -> "Project..." and choose "Java Project". Then, in the new project creation dialog, enter a project name and choose "Create project from existing source". In the "Directory" field, choose your BattleCode installation directory and click the "Finish" button at the bottom of the dialog.
When it finishes, Eclipse will add the "teams" folder as a source folder and add the included jar files to your build path. (If you installed Ant, you'll see a lots of files beginning with "ant-" on your build path. You can safely remove them from your build path, but don't delete them!) You can begin developing a player.
When you're ready to run a match, right click the "build.xml" file in your project root directory and choose "Run As" -> "Ant Build". You can re-run the match software by choosing the external tools runner in the Eclipse toolbar (the green-and-white run icon with a small bag beneath it).
Local matches are the most common way to run a match - they are computed and rendered simultaneously on the same machine. To run a "local" match, use the ant run command from your installation directory. (If you're not using Ant, you can run the battlecode.main.Main class from the command line or an IDE.)
When running a local match, you also have the option of saving the match to a file so that you can play it back without having to recompute it. To do this, check the "Save match to file" box on the main dialog and choose the location of the file. Note that the file will be overwritten if it already exists.
It is also possible to compute and view matches on two separate machines via TCP/IP. Let's say you have two machines -- A, which has the players you've written, will be the machine that computes the match; B will be the machine that views the match.
First, on machine A, use "ant server" to run a match server. Then, on machine B, use "ant run" to run the main dialog. Choose "Connect to remote match server" on the dialog and enter the host or IP address of machine A. When you've entered the address, the dialog on machine B will ask machine A for the teams and maps it knows about, so you can choose them from the dropdown list.
If you have a match file that you'd like to play back (i.e., from saving one previously) you can choose "Play back from match file" and choose the match file to play back. The remainder of the dialog settings will be ignored.
A dialog box will appear that allows you to choose the teams and maps to run. The teams and maps that appear in the dropdown boxes are those that the software knows about at runtime. If the team or map you're trying to run does not appear in the dropdown box, it isn't on your classpath or map path.
This year, each match between two teams consists of a set of games. To run multiple games in a match, use the add and remove buttons below the map dropdown box to add maps to the list. A game will be played on each map in the list, in order. If you don't add any maps, the match will consist of one game, on the map selected in the dropdown box.
Normally, the software computes the match well ahead of what is being currently viewed. However, selecting "compute and view match synchronously" from the match dialog puts the software in "lockstep mode", where the computation and viewing move in lockstep. This is generally slower than running them independently, but it allows for some interesting debugging features.
While in lockstep mode, right-clicking on an open square in the map brings up a menu that lets you add new units to the map. Right-clicking on an existing unit allows you to set its control bits, which the robot's player can query and react to. You can also drag-and-drop units on the map.
These debugging features are intended to help you test your robots in situations that might otherwise be hard to get them into (e.g., what happens if one of my archons gets cut off from the rest...?). However, if the players are not written defensively, these unexpected manual changes can interfere with their control logic. Keep this in mind when using the debugging features.
Also, during the tournament and scrimmages, you will not be able to manually affect the game in this way.
The BattleCode distribution includes a configuration file, "bc.conf", that allows you to tweak some of the software's settings. Appendix A contains a listing of configurable properties.
The properties can also be set in any way that Java properties are set. This includes using "-D[property]=[value]" on the java or ant command line.
When running a local match, the game engine attempts to periodically delay to prevent starving the match viewer of CPU time. Altering the following two settings may yield better local match performance:
bc.server.throttle: determines how to delay match computation; can be set to either "yield" or "sleep"
bc.server.throttle-count: the number of rounds between sleep/yield
The following settings can be used to enable or disable certain aspects of the engine.
bc.engine.debug-methods: "true" or "false"; whether or not the engine will run debug methods for free
bc.engine.silence-a and bc.engine.silence-b: "true" or "false"; whether or not the engine will suppress printouts for the appropriate team
bc.engine.gc: "true" or "false"; whether or not to periodically force garbage collection in the game engine -- this option causes decreased performance but may help if the virtual machine runs out of memory during computation
bc.engine.gc-rounds: how many rounds between forced invocation of the garbage collector; the default is 50
bc.engine.upkeep: "true" or "false"; if "false", the engine will not charge units their energon upkeep each round
bc.engine.breakpoints: "true" or "false"; if "false", the engine will skip breakpoints in player code
"Headless" mode runs matches without displaying them in a client. This mode can be run via "ant file" in the installation, or with a "-h" argument when calling the Main class directly.
bc.game.team-a: the name of team A when running "headless" matches
bc.game.team-b: the name of team B when running "headless" matches
bc.game.maps: a comma-separated list of map names for headless matches, with no spaces between them and no ".xml" suffix (i.e., bc.game.maps=orb,trap)
bc.game.save-file: the relative path and name of the match file to write when running a headless match
bc.game.map-path: the folder in which to look for map files
bc.dialog.skip: "true" or "false"; whether or not to show the setup dialog when the software is started. If "true", the parameters most recently entered into the dialog will be used.
-c (config file name): use the specified config file when running the match; defaults to bc.conf in ant
-h: use "headless" mode (see above); equivalent to "ant file"
-s: use "server" mode -- listen for a connection from a remote client and send match data via TCP; equivalent to "ant serve"
-n: skip the match dialog; equivalent to bc.dialog.skip=true config file option (see above)