Home | Register | Login

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. The game binary includes a JAR file to let you run games. 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++, C#, and Java.

Making Something Happen

If you just want to see a game running, you can type the following command. This will start the game with a basic 2D view and without any player code associated with either player. Bumpers will sit still and the sleds will just drive across the field.

java -jar capture.jar

Using Built-In Players

If you want to see the players do something a little bit interesting, you can run the game with the following options. This will associate simple, built-in code for each of the two players. The red player will be controlled by a player called RandomPlayer, one that just generates a new, random move every 10 turns. The blue player will be controlled by a copy of LoopyPlayer, one that drives its pieces in circular arcs.

java -jar capture.jar -player builtin RandomPlayer -player builtin LoopyPlayer

There are three built-in players available, RandomPlayer, LoopyPlayer and DoNothingPlayer. These players don't do much to make the game interesting, but they do provide very simple opponents that should be easy for you to beat.

Running a C++ Player

Let's say you've implemented a player in C++. You've compiled your player to an executable called "hunter". You can run this player as the red player using the following command line. You will be playing against a copy of the built-in LoopyPlayer.

java -jar capture.jar -player cpp hunter -player builtin LoopyPlayer

Running a Java Player

Let's say you've implemented a player in Java. You've compiled your player to a class called "Gatherer". You can run this player as the blue player using the following command line. Here, you will be playing against a copy of the built-in RandomPlayer.

java -jar capture.jar -player builtin RandomPlayer -player java Gatherer

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 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. Keep in mind that, during tournament matches, your player won't be passed any command-line arguments.

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 hunter C++ program as the blue player and the Gatherer Java program as the red player.

java -jar capture.jar -player pipe 2 java Gatherer -player pipe 1 hunter

Alternative Visualization

The simple 2D view that's provided by default is intended to give a basic, low-overhead visualization of what's going on in the game. This view should work reasonably well on just about any system and doesn't require installation of any additional libraries.

The Queue ICPC Challenge distribution also includes a 3D view. To use this view, you have to have the JOGL package installed on your machine. In particular, you have to have the JOGL jar files visible in your CLASSPATH and the dynamic-link libraries visible in your library path. You can find JOGL binaries for a variety of platforms and installation instructions at: https://jogl.dev.java.net/

Once you have JOGL configured, the easiest way to run the game is to just add capture.jar to your CLASSPATH. If you do this, then you can run with the 3D view using a command line like the following:

java icpc.challenge.main.Game -player builtin RandomPlayer -player builtin LoopyPlayer -view 3D

Playing the Game

In single-player mode, the user can direct the actions of one of the game pieces. This can help the programmer to come up with creative strategies by playing one of the pieces and letting their code play the other two. The -player sled option lets the user control the sled with the left and right cursor keys. This can be followed by the same options used to specify a built-in or an external player. For example, the following command line will play the built-in LoopyPlayer against the built-in RandomPlayer. However, the user will control the operation of the RandomPlayer's sled.

java -jar capture.jar -player builtin LoopyPlayer -player sled builtin RandomPlayer

The -player bumper0 option lets the user control one of the bumpers, while a player implementation controls the other two pieces. For example, the following command line could be used play the built-in RandomPlayer against a C++ player called "hunter". The C++ implementation will control the sled and one of the bumpers and the the user will control the remaining bumper with the four cursor keys. Although bumpers don't normally experience friction, when a user is controlling one of the bumpers, a small amount of friction is applied after each move in an effort to make the bumper easier to control.

java -jar capture.jar -player bumper0 cpp hunter -player builtin RandomPlayer

The -player bumper1 option works just like -player bumper0, but lets the user control the other bumper.

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

java -jar capture.jar -player pipe 2 java Gatherer -player pipe 1 hunter
     -view trace trace.txt

After you generate a trace file, you can play it back with a trace player. If you've added capture.jar to your CLASSPATH, then the following command will play back this trace using the basic view to show the contents of trace.txt.

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 omits some of the information that is available to the players and 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 like the following will create a turn history file called ``turns.txt'' that contains the sequence of states as seen by the red player. In the turn history, each state is followed by the move response that was received from each of the players.

java -jar capture.jar -player java Gatherer -player exe  hunter -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 capture.jar to your CLASSPATH, The following command will play back a game from its turn file.

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

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.

Real-Time ResponseSynchronous Mode
-player java -player syncjava
-player cpp -player synccpp
-player pipe -player syncpipe