Usage Instructions

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 CLASSPATH and specifying some other class as the entry point.

Making Something Happen

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

Game Visualization

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 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.

java -jar coercion.jar -player cpp c++_example/gather -player java \
     -cp java_example Migrate -view simple60

Running a C++ Player

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

Running a Java Player

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, -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.

Running an Arbitrary Player

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.

java -jar coercion.jar -player pipe 2 java Lucy -player pipe 1 bill

Running a C#, Python or Javascript Player

The game engine doesn't have explicit support for C#, Python and Javascript, but you can use the -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 icypc.jar -player pipe 2 mono playerOne.exe -player pipe 2 python playerTwo.py

java -jar coercion.jar -player java Ernie -player pipe 2 rhino bert.js

Recording a Game

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 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

Recording a Turn History

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 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 you've added coercion.jar to your CLASSPATH, The following command will play back a game from its turn file.

java icpc.challenge.view.TurnPlayer -turns turns.txt

Alternative Maps

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 -map 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 like:

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.

Synchronous Operation

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.