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:
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.
(Windows) Edit system PATH to include jdk/bin directory for javac and java
Turn off firewall
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
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
Edit server/server_settings.ini to suit your tournament needs
Run server/run_server.bat
If previous results exist, server will ask to resume tournament
If you do not resume a tournament, server will ask to delete previous results
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.
Server will check if required files exist before launching GUI
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)
Edit system PATH to include jdk/bin directory for javac and java
32bit Windows: Edit registry so that HKLM\SOFTWARE has "Full Control" for current user
64bit Windows: Edit registry so that HKLM\SOFTWARE\Wow6432Node has "Full Control" for current user
Copy client/ directory to client machine
Running Client Software
Edit client/client_settings.ini to match your tournament setup
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.