Student StarCraft AI Tournament Tutorial for Getting Started with C++

The Student Starcraft AI tournament is an ongoing competition to write a bot to compete in playing 1v1 games of the real-time strategy game Starcraft. I found the documentation on how to get started to be scattered and lacking, and I hope to consolidate the knowledge I gained here into a mini-tutorial that will lower the barrier for entry.

PART 1 - Running the Example AI

First, you will need Starcraft Brood War patched to version 1.16.1 installed (You do not need the CD to run the game if you follow the instructions in the patch notes for version 1.15.2).

Next, you will need to download and extract BWAPI version 3.7.4 which is  not the latest version, however it is the version used by the SSCAI tournament.  I found that the included installer does not work, as confirmed by bug reports which were addressed in later versions.  However, later versions do not help us, as we need version 3.7.4 for the tournament.  Once extracted, the readme says

2. Run "install.exe". This will do the following:
    * Copies the contents of ./WINDOWS/ to the C:/Windows folder.
    * Copies the contents of ./Starcraft/ to your actual Starcraft folder.
    * Performs additional minor installation steps.

so, assuming the "additional minor installation steps" are nothing of importance, we can manually install BWAPI by copying the files according to the above instructions.  (This is what I did, and everything seems to have worked for me).

Next, you  need to install Visual Studio 2008 (the version is important, as later versions will give you errors when you try to compile).  You don't need to buy the full version, as Visual C++ 2008 Express Edition works fine, and is freely available for download.

When Visual Studio is installed, we will try using it to compile the example project and test it.  To do so, open up ExampleProjects.sln from the root directory of BWAPI in Visual Studio, and select Build>Build Solution from the menu bar.  When this is completed, check the output tab at the bottom for build errors (there should be none, if there are any errors, good luck!) .

To run the example AI module

1. Copy Release/ExampleAIModule.dll to
   <starcraft folder>/bwapi-data/AI/ExampleAIModule.dll

2. Open <starcraft folder>/bwapi-data/bwapi.ini and set ai to
   bwapi-data/AI/ExampleAIModule.dll if it isn't already.
 
3. Run Chaoslauncher with BWAPI Injector checked. You can also check W-MODE
   to have Broodwar run in a window rather than full-screen.

For the second step, this simply means editting the line in bwapi.ini which starts with

ai     =

to say

ai     =  bwapi-data/AI/ExampleAIModule.dll

You can also choose to build the debug version in Visual Studio.  In that case, you would copy the dll from Debug/ExampleAIModule.dll and modify the line starting with ai_dbg instead.  When starting up starcraft, you will have an option to choose between running debug mode or not, and the AI from the appropriate DLL will be loaded.  Nothing else in the bwapi.ini file needs to be edited for now.

Chaoslauncher can be found in the BWAPI main directory under Chaoslauncher/Chaoslauncher.exe.  When you open it, you can see the choice of checking off the BWAPI DEBUG or RELEASE options.  Check off just one, and optionally W-MODE (I suggest using debug mode and W-MODE), and click start.  You can safely ignore a warning about admin privileges if it pops up.  From here, you just need to get into a Starcraft game, and BWAPI should take over with the example AI.  The quickest way is to select a single-player expansion custom game and start the game.  The Example AI module should print some debug text to the screen and issue some basic commands to your probe and command center. If this happens, you have successfully completed the first step on getting your own BWAPI bot to run.

PART 2 - Creating your own AI Project