Home Compete Results Rules Software Archive Contact


StarCraft AI Competition - Tournament Manager Software

Contents

Software Download

Download the Tournament Manager Software from github

Zip file containing all Visual Studio redists and easy install script: all_vcredist_x86.zip (50,608kb)

The tournament manager software download includes precompiled server and client jar files, as well as the complete Java 7 source code. It also includes several required files for setup such as Chaoslauncher and necessary Windows .dll files which will automatically be configured and run for you. Also included are the bots and maps from the 2013 AIIDE StarCraft AI Competition. With these files you should be able to run a tournament as quickly as you can install StarCraft on all of your client machines!

Bug Reporting

Please report any bugs in this software to me at dave.churchill@gmail.com. I will answer any questions you have about the software, fix bugs, or add (reasonable) features upon request.

Disclaimer

Keep in mind that this is not retail software, and I am not responsible for any negative effects it has on your system. This software regularly creates, deletes, and sends files over sockets, and I am not a perfect programmer. Use this software at your own risk. That being said, it *should* work without many issues.

Introduction

In order to play as many games of StarCraft as possible, the AIIDE StarCraft AI Competition uses custom-built tournament managing software which can automatically play scheduled StarCraft AI games in a LAN setting. This tournament managing software uses a server-client architechture with one machine acting as a server and any number of other machines acting as clients. The tournament manager is written entirely in Java, and can be run on any version of Windows (XP or higher), either on a physical machine or a virtual machine. All data sent and received is compressed and passed through Java sockets, so no special network configuration is required to run the software.

Server

When running the software, one machine acts as a server for the tournament. The server is a central repository where all bot files (including file I/O) data, cumulative results, and replay files are stored. The server also monitors each client remotely and outputs status and results to an html file so that tournament status can be viewed in real time.

The server program has a threaded component which monitors for new client connections and detects client disconnections, maintaining a current list of clients which can have one of the following statuses: READY - Client is free and ready to start a game of StarCraft, STARTING - Client has started the StarCraft LAN lobby but the match has not yet begun, RUNNING - Client is currently running a game of StarCraft, SENDING - Client has finished the game and is sending results and data back to the server. When a client initially connects to the server, the server sends it the Chaoslauncher program automatically.

The server's main scheduling loop tries to schedule the next game from the games list every 2 seconds. A new game can be started only if two or more Clients are READY, and no clients are STARTING. The reason no clients can be STARTING is to prevent multiple StarCraft game lobbies to be open on the same LAN, which may cause mis-scheduled games due to limitations on how we are able to join games automatically. Once these two conditions are met, the server sends the required bot files, map files, and chaoslauncher configuration to the client machines, specifying one client as the host and one as the away machine. Those clients' status are then set to STARTING.

Each client is handled by a separate thread in the server, and if the client is STARTING, RUNNING, or SENDING, it sends periodic status updates back to the server for remote monitoring. Data such as current game time, time-out information, map, game ID, etc are each updated once per second from each client to the server GUI. When a client finishes a game the results are sent back to the server along with file I/O data and replay files, which are all stored on the server. This process repeats until the tournament has finished.

Shutting down the server via the GUI will cause all client games to stop and all client software to shut down and clean up properly. The tournament can be resumed upon re-launching the server program as long as the results file and games list do not change.

Client

The client software can be run on as many machines that are avaialable on your LAN. After an initial setup of the client machine (installing StarCraft, etc) the client software connects to the server machine to await instructions. Upon initially connecting to the server, the client recieves the Chaoslauncher program and automatically updates the Windows registry with the required StarCraft and Chaoslauncher settings.

The client machine will stay idle until it receives instructions from the server that a game is to be run. Once the client receives the required files from the server, it ensures that no current StarCraft processes are running, records a current snapshot of the running processes on the client machine, writes the BWAPI settings file for Chaoslauncher, and starts the game. When the game starts, a custom BWAPI Tournament Module is injected via Chaoslauncher which outputs a GameState file to disk every few frames, which monitors the current state of StarCraft. The client software reads this file to check for various conditions such as bot time-outs, crashes, no game frame progression, and game termination. As the game is running, the client sends the contents of the GameState file to the server once per second to be monitored on the server GUI.

Once the game has terminated for any reason, the results of the game, replay files, and file I/O data are sent back to the server. Once the sending is complete, the client software shuts down any processes on the machine which were not running when the game began, to prevent things like crashed proxy bots or stray threads from hogging system resources from future games. StarCraft is shut down, the machine is cleaned of any files written during the previous game, and the client status is reported back to the server as READY.

Software Instructions

Prerequisites

Running a tournament using this software requires the following prerequisites:

Download & Compile

Once the tournament manager software has been downloaded from the link above, you can extract it to any directory on your sever machine that does not contain spaces (I am a lazy programmer). Once extracted, you will find the following directory structure:

        TournamentManager/
            client/                       Client Directory
                BWAPI.ini                     Default BWAPI settings file
                client.jar                    Client jar file
                client_settings.ini           Client settings file (modify this)
                run_client.bat                Script to run client
            server/                       Server Directory
                bots/                         Contains all files for each bot
                    botname/                  Bot-specific directory
                        AI/                       Where the .dll / proxy bot files go
                        read/                     File I/O read directory
                        write/                    File I/O write directory
                html/                         Generated HTML file directory
                replays/                      Replay storage directory
                required/                     Required file storage directory
                    Chaoslauncher.zip             Chaoslauncher program files
                    Required_BWAPI_374.zip    BWAPI/Starcraft required files (BWAPI 374)
                    Required_BWAPI_401B.zip   BWAPI/Starcraft required files (BWAPI 401B)
                games.txt                     Default tournament games list filename
                results.txt                   Default tournament results filename
                run_server.bat                Script to run server
                server.jar                    Server .jar file
                server_settings.ini           Server settings file (modify this)
            src/                          Source Code Folder
                packagename/                  Source package directories
                clean.bat                     Script to delete all .class files in subdirs
                make.bat                      Script to compile / make jar files

The tournament manager comes pre-compiled as 2 jar files (client/client.jar, serverserver.jar), however if you want to compile the code you can use clean.bat and make.bat in the src/ folder, or any other build system you wish. The make.bat script will compile the necessary Java files, create the required .jar files and put them into the correct sub-directories.

Initial Server Setup

  1. Install Java JDK 7
  2. (Windows) Edit system PATH to include jdk/bin directory for javac and java
  3. Turn off firewall
  4. The following directory structure must exist for each bot in the tournament:
    • server/bots/BotName/ - Bot directory
    • server/bots/BotName/AI/ - Holds all AI files for each bot including BotName.dll
    • server/bots/BotName/AI/BotName.dll - Bot .dll must be named the same as folder
    • server/bots/BotName/AI/run_proxy.bat - If bot is a proxy bot, this file must exist
    • server/bots/BotName/read/ - Bot read directory
    • server/bots/BotName/write/ - Bot write directory
  5. Put your map files inside the server/required/Required_* zip files under the 'maps' folder

Note: The tournament manager comes with the bots and maps which competed in the 2013 AIIDE StarCraft AI Competition. Make sure that each bot and map you change is listed correctly in server/server_settings.ini

Proxy Bots: The file server/bots/BotName/AI/run_proxy.bat is a file which must exist if your bot is listed as 'proxy' in server_settings.ini, it will be run on the client machine immediately BEFORE StarCraft is launched, and must contain all code necessary to launch your proxy bot. All proxy bot files must be stored in the server/bots/BotName/AI/ directory (subdirectories allowed), since this is the folder which is copied to the client machine before a game starts.

Running Server Software

  1. Edit server/server_settings.ini to suit your tournament needs
  2. Run server/run_server.bat
  3. If previous results exist, server will ask to resume tournament
  4. If you do not resume a tournament, server will ask to delete previous results
  5. If a games list file does not exist, server will prompt to generate one. It will generate a round robin tournament based on the bots and maps in server_settings.ini. Currently only round robin tournament games generation is supported, however you can edit the games list manually as long as you follow the existing syntax.
  6. Server will check if required files exist before launching GUI
  7. Once the GUI has started, launch client software on client machines

Results Output:

  • Raw results are written to server/results.txt after each game ends
  • HTML results are written every 2 seconds to server/html/
  • Detailed HTML match results can be written manually via the Server GUI, or automatically once every minute if you turn on the option in the server settings file. It is off by default due to long processing times for large tournaments.
  • Replay files are saved to server/replays/
  • Bot read/write directories are stored in server/bots/BotName/(read|write)

Initial Client Setup

  1. Install StarCraft: BroodWar to a directory containing no spaces
  2. Upgrade StarCraft to latest version 1.16.1
  3. Install Microsoft Visual C++ Redists
  4. Install Java JDK 7
  5. Edit system PATH to include jdk/bin directory for javac and java
  6. 32bit Windows: Edit registry so that HKLM\SOFTWARE has "Full Control" for current user
  7. 64bit Windows: Edit registry so that HKLM\SOFTWARE\Wow6432Node has "Full Control" for current user
  8. Copy client/ directory to client machine

Running Client Software

  1. Edit client/client_settings.ini to match your tournament setup
  2. Run client/run_client.bat

Note: Exactly one client instance can be run per machine. Clients can be run on a physical or a virtual machine, as long as your LAN settings can handle StarCraft's UDP communication. One client can be run on the same machine as the server. I regularly run sample tournaments with the server and one client running on a physical machine, with a 2nd client running in a VM.