The game engine is implemented in Java and supports several command-line options to let the user run games with different players and with different output behavior. Since players are implemented as separate executables, the developer is free to use any development environment to code the player behavior. In principle, any programming language may be used to implement a player, but the submission site will only accept players written in C++ and Java.
When you download the game distribution binary, you will receive a zip file containing a small directory structure for the game. The jar file, bbr.jar, contains the executable code for the game, and other subdirectories contain sample map files and example players implemented in C++ and Java.
The bbr.jar file has the main game class (icpc.challenge.main.Game)
defined as its entry point. You can run matches by simply giving this
jar file as an argument to the Java interpreter.
Alternatively, you can run other classes in bbr.jar by putting
bbr.jar in your CLASSPATH and
specifying some other class as the entry point.
If you just want to see a game running, you can unpack the game distribution binary and run the following command from the top-level directory. This will start the game with a basic 2D view of the field and with two copies of the example Java player competing against each other.
java -jar bbr.jar -player java -cp java_example HotPotato \
-player java -cp java_example HotPotato
The game distribution binary contains a basic 2D visualization. This visualization shows the field from above and gives an indication of which boat has the baton, which way each boat and its thrust are pointing and how much progress has been made toward completing the current lap. For the tournament, we will use a 3D visualization that should make the games look more interesting.
The default view may be too large for users with small screens. To
help with this, the game, the trace player and the turn player
(described below) accept a -view simple80 and
a -view simple60 option. These options create a view of
the game that is 80 percent or 60 percent of the width and height of
the standard view. For example, the following will show a match
between the two example players using a reduced view size. This
assumes you've compiled the C++ example player on your system.
java -jar bbr.jar -player cpp c++_example/hotPotato -player java \
-cp java_example HotPotato -view simple60
Let's say you've implemented a player in C++. You've compiled your
player to an executable called bill. You can run this
player as the red player using the following command line. You will
be playing against a copy of the example player, HotPotato.
java -jar bbr.jar -player cpp bill -player java -cp java_example HotPotato
Let's say you've implemented a player in Java. You've compiled your
player to a class called Lucy. You can run this player as
the blue player using the following command line. Here, you will be playing
against a copy of the Java example player.
java -jar bbr.jar -player java -cp java_example HotPotato -player java Lucy
Remember that Java players are expected to reside in the default Java
package. For Java players, the command-line option, -cp,
lets you specify a class path for a Java player. We have to do this
with the example Java players, since they don't have a package prefix,
but they are located under the java_example directory. If your Java
class files are in the current directory or are already accessible
from the CLASSPATH, you should not need to use
the -cp option.
The above examples of running a player as a C++ executable or as a
Java program are really just special cases of the same start-up mechanism. The
game engine's -player pipe option gives a more general
mechanism for running the player executable. This method for starting
up a player can let you pass in additional command-line parameters to
the player if these are useful during development.
The pipe keyword is followed by an integer, n. The
next n command-line arguments are taken as the command line
for the executable that is to serve as the player. For example, the
following command line could be used to run the C++ program,
bill, as the blue player and a Java
program, Lucy, as the red player. Here, the bill player
is passed the word "greedy" as an extra command-line argument.
java -jar bbr.jar -player pipe 2 java Lucy -player pipe 2 bill greedy
If you want, you can send a record of game events to a trace file for
later viewing. The following command will create a rather large trace
file called trace.txt containing the sequence of game events.
java -jar bbr.jar -player java Lucy -player cpp bill \
-view trace trace.txt
After you generate a trace file, you can play it back with a trace player. If you've added bbr.jar to your CLASSPATH, then the following command will play back this trace.
java icpc.challenge.view.TracePlayer -trace trace.txt
The trace file generated by the -view trace option
records game event information used by the game's visualization
components. It includes extra information that players don't get to
see. The -view turns option is intended to capture the
sequence of messages exchanged between the game and its two players.
Running a game with a command like the following will create a turn
history file called turns.txt that contains the initial
map followed by the sequence of game states as seen by the red player.
In the turn history, each game state is followed by the move response
that was received from each of the players.
java -jar bbr.jar -player java Lucy -player cpp bill -view turns turns.txt
A turn history is intended to help developers debug their players. The file reports game states and moves as seen by the game engine. The re-mapping of game locations and directions normally done when interacting with the blue player is not apparent in this report.
A game can be visualized using its turn file. Since the turn file
omits some of the information that's included in a trace, the
visualization will not be as smooth and it will not include all
effects. However, it can still be useful to give the developer a
sense of what was going on at a particular point in the game. If
you've added bbr.jar to your CLASSPATH, the
following command will play back a game from its turn file.
java icpc.challenge.view.TurnPlayer -turns turns.txt
By default, the game uses a map like the one pictured in
the playing field
section of the rules. In the preliminary matches and in the final
tournament, the map, including boat configurations, field size,
initial boat locations and course shape, may vary from match to match.
You can try out your player with alternative maps using
the -map option. This option requires the name of a text
file. To run a match with an alternative map, you can use a command
like:
java -jar bbr.jar -player java Lucy -player cpp bill -map maps/map2.txt
The format of the map description is similar, but not identical to the start-up game state sent to the player. The map file starts with a floating point field size, representing the width and height of the playing field.
The field size is followed by a description the configuration of of the five red player's boats. Initial blue-player boats are just a 180-degree rotation of the red boats, so these are not included. Each boat is described by a line of nine floating point parameters, the boatRadius, the X and Y location of the thrustPosition relative to the boat center, the thrustStrength, the thrustRange for the thrust, and the mass of the boat. These parameters are described in the boats section of the rules. The next three values give the initial X and Y position of the boat's center and the initial boat heading.
The list of boat configurations is followed by a description of the red player's course. The blue player's course isn't given, since it's always a 180-degree rotation of the red player's course. The course description starts with a positive integer, n, giving the number of rally points on the course. This is followed by the sequence of n rally points on the red player's course. Each rally point is given on a line by itself, as a floating point X coordinate followed by a Y coordinate.
For debugging, players can be started in synchronous mode. This
forces the game engine to wait for every move from the player before
simulating the next game turn. The following table shows the variants
of the -player option that can be used to request synchronous
operation with a particular player.
| Real-Time Response | Synchronous Mode |
| -player java | -player syncjava |
| -player cpp | -player synccpp |
| -player pipe | -player syncpipe |