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, coercion.jar, contains the executable code for the game, and other subdirectories contain sample map files and example players implemented in C++ and Java.
The coercion.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 the first argument to the Java interpreter.
Alternatively, you can run other classes in coercion.jar by putting
coercion.jar in your
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 coercion.jar -player java -cp java_example Migrate \ -player java -cp java_example Migrate
The game distribution binary contains a basic 2D visualization. This visualization shows the field from above and gives indications when a marker or a region is under pressure from a different color. 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
-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.
java -jar coercion.jar -player cpp c++_example/gather -player java \ -cp java_example Migrate -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, Migrate.
java -jar coercion.jar -player cpp bill -player java -cp java_example Migrate
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 coercion.jar -player java -cp java_example Migrate -player java Lucy
Remember that Java players are expected to reside in the default Java
package. For Java players, the command-line option,
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
CLASSPATH, you should not need to use
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
-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.
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
Lucy, as the red player.
java -jar coercion.jar -player pipe 2 java Lucy -player pipe 1 bill
-player pipe option to run players in these languages. For example, if you wanted to run a C# player via mono against a python player, you might start the game like this:
java -jar coercion.jar -player java Ernie -player pipe 2 rhino bert.js
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
trace.txt containing the sequence of game events.
java -jar coercion.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 coercion.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
-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 coercion.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 colors, 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
coercion.jar to your
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 with
the short game
description. In the preliminary matches and in the final
tournament, map geometry may vary from match to match. You can try
out your player with alternative maps using the
option. This option requires the name of a text file containing a map
description exactly like the one players receive at the start of the
game. To run a match with an alternative map, you can use a command
java -jar coercion.jar -player java Lucy -player cpp bill -map maps/map2.txt
Maps are somewhat difficult to generate, but a few sample maps are
included under the
maps directory of
the game distribution binary.
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
-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|