The Battlecode software consists of three major components:
The Battlecode software requires:
The following hardware is recommended for best performance:
Ensure that you are using the correct version of Java.
We recommend that you install either Apache Ant, Eclipse, or Netbeans.
Battlecode will run on Java 8. Please be aware, however, that the scrimmage server runs Oracle Java 7, and it will not be able to compile your code if you use Java 8 specific language features.
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
If you are working from Athena, you shouldn't have to do anything special to get Battlecode running; you can follow these instructions exactly. The path to the JDK will be something like
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.
build.xml file 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
After you've placed your source code there, navigate to the installation directory and run:
This command will invoke the Java compiler on all source code in the
If you ever have any trouble, one useful command is:
Building after running this might help resolve issues with version changes.
Apache Ant is a Java-based build system similar in theory to UNIX
On every system you will need to set the JAVA_HOME environment variable to point to the installation path of your JDK.
You may also need the ANT_HOME environment variable in some cases. Just set this to be the path to your ant installation and you should be good to go.
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.
You can check which version of Java Ant is using with the command
Update to Eclipse 4.2 or higher if you have not done so already. After you have installed the software, open Eclipse and choose "File" -> "New" -> "Project..." and choose "Java Project from Existing Ant Buildfile". Navigate to the build.xml in your install folder and use this one. Name your project, or leave it as the default and click 'Link to build file in the filesystem' and click 'Finish'. Alternatively, you can use "Java Project from Existing Source" and then in the import screen click the (+) next to teams.
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.client.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 serve to run a match server. Then, on machine
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.
You should upload a zip or jar file containing your team's source code.
You should use the package name
teamXXX where XXX is your team number.
You can build this jar automatically using the command
ant -Dteam=teamXXX jar
Alternatively, creating a zip file of the
teamXXX directory should work.
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
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
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 headless" in the installation, or with a "-h" argument when calling the Main class directly.
bc.game.renderprefs2d: preferences for the 2d client. For example, if you wanted to turn off the rendering of broadcasts and gridlines, you could set this property to "bg". See the "Shortcut Keys" section for a complete listing of toggles.
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
-h: use "headless" mode (see above)
-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=trueconfig file option (see above) == Client Settings ==
bc.client.renderprefs2d: A list of toggles to set in the 2D client. (See Shortcut Keys below.) For example, if you want to turn off broadcasts, grid lines, and transfers, you would set
bc.client.sound-on: "true" or "false"; whether or not to play sound effects. == Shortcut Keys ==
|B||Toggle unit broadcasts|
|D||Toggle discrete movement mode|
|E||Toggle HP bars|
|F||Toggle fast forward|
|G||Toggle grid lines|
|H||Toggle action lines|
|I||Rewind 50 rounds|
|J||Toggle slow mo|
|L||Toggle low supply indicators|
|K||Toggle attack lines|
|R||Show attack/sight ranges when examining a unit|
|S||Skip 100 rounds|
|T||Toggle supply transfers|
|U||Toggle ore display (important ores only, all ores, or no ores)|
|V||Toggle indicator dot/line display (none, one team, both teams)|
|X||Toggle unit explosions|
|/||Find unit by ID|
Most contestants choose to write their players in Java, but we also support
Scala (or a mix of Java and Scala). If you want to use Scala, you should
download scala-compiler-2.11.4.jar, scala-libary-2.11.4.jar, scala-reflect-2.11.4.jar, and jline-2.12 and place them in your
download scala-compiler-2.11.4.jar, scala-library-2.11.4.jar, and scala-reflect-2.11.4.jar and place them in your
lib directory. We have a simple example player written in Scala that you can download here.