DTC: Runner guide

We provide you with an executable jar file which can be used to test and visualize your submissions while you work on them. You need Java 8 (or 11) to run it (the runner does not work with any other version). You can run the game runner from the command line using java -jar runner.jar <args>. Running the jar without any additional arguments will result in the following instruction message:

DTC Game Runner

Usage:
  java -jar runner.jar <submission1> <submission2> [--seed <seed>] [--time <time>] [--file <file> | --port <port>]
  java -jar runner.jar <game result> [--port <port>]
  java -jar runner.jar --help

Options:
  -s <seed>, --seed <seed>  Specify the seed when running the game.
  -t <time>, --time <time>  Specify the total time limit per bot in milliseconds.
  -f <file>, --file <file>  Specify a file to store the game result at.
  -p <port>, --port <port>  Specify the port for the local visualization web server.
  -h --help                 Show this information.

The jar can be used to perform multiple tasks. When specifying two submission arguments (which are paths to submission source files), it will compile the submissions and run a game between the two submissions. The submissions can point to the same file, in which case two duplicates of the bot will play against each other. The seed that is used for this match is random unless explicitly specified by --seed. The total time limit per bot is set to 30 seconds, except if specified by --time. Setting this to a low value makes debugging much easier. The result of the game is then further processed by either writing it to a file (specified by --file) or starting a local web server. This local web server is used to visualize the result recently generated. It will start on the specified port or on 8080 (the default). Immediately after, this visualization is opened in your browser. A stored game result file can later be viewed using the runner by specifying the game result file as argument, which will open the same local web server. To interrupt the process and stop the web server you can use the key combination ctrl+c (Windows) or command+. (MAC).

Java may print some warnings about illegal reflective access; these can be ignored.

Example usage

java -jar runner.jar JavaAgent.java python_agent.py -s 12 -p 8000: Compiles the Java submission JavaAgent and Python submission python_agent. Plays a game using seed 12 and visualizes the result on port 8000.

java -jar runner.jar JavaAgent python_agent.pyc -f game.json: If JavaAgent is a directory consisting of compiled Java class files and python_agent.pyc is a compiled Python submission, the runner plays a match between them on a random seed and stores the result in game.json.

java -jar runner.jar game.json: Reads the game result stored in game.json and opens a local web server using the default port 8080 to visualize the result.

Configuration

The runner makes use of a configuration file runner-config.json which it will automatically generate if not yet present. Generally, it can be left untouched. It specifies the command line commands that are used to compile and run submissions. If your .NET, JDK, or Python installation is located at non-standard locations you can edit these in the configuration. An example of a configuration that uses a Python installation provided by Anaconda 3 is shown below.

{
  "csharp-compile": [
    "dotnet new console -f net6.0 --force -o $dir",
    "dotnet build -c Release $dir"
  ],
  "csharp-run": "dotnet run -c Release --no-build --project $dir",
  "java-compile": "javac -encoding UTF-8 $source -d $dir",
  "java-run": "java -Dfile.encoding=UTF-8 -XX:+UseSerialGC -cp $classpath $main",
  "python-compile": "C:\\ProgramData\\Anaconda3\\python -m py_compile $source",
  "python-run": "C:\\ProgramData\\Anaconda3\\python $file"
}