Getting started for the Ladder Manager from scratch (C++)

From Starcraft 2 AI
Jump to: navigation, search

Following this guide will give you a bot that could already compete in the Starcraft 2 AI Ladder but it is basically blank. The advantage of this approach is that your bot has no hard to find "inherited" bugs and you do not have to work in an framework that is maybe not optimally tailored to your programming style. The downside is that is might take you a little longer until you have your first win against another bot. CryptBot is an example bot that started from scratch.

If instead you want to start with a generic, more complex bot try this guide.


The SC2api will use some pre-cached data. Therefore to be safe, we need to play one game on the map used for debugging.

  1. Download Starcraft II (it is free).
  2. Start the game.
  3. Go to Custom->Melee and search for Interloper LE. (If it only appears with mod, close the search, select Blizzard maps, and scroll down a bit.)
  4. Create lobby.
  5. Start Game.
  6. Once the game started, you can immediately leave and close the game.


If you already have the s2client-api installed feel free to jump to the next section. Nevertheless, it is recommended to double-check that all steps were done exactly as described below.

  1. Install Visual Studio Community 2017. Chose the C++ IDE.
  2. Start a cmd prompt (cmd.exe).
  3. Follow the instructions here.
  4. After this Visual Studio 2017 should be open.
  5. In the top row select "Release" and "x64".
  6. Build -> Build Solution.
  7. In the top row select "Debug" and "x64".
  8. Build -> Build Solution.
  9. Close Visual Studio.
  10. Open the folder "<path to>\s2client-api".
  11. Execute, i.e. double click on "synchproject.bat".
  12. Answer with "yes" or "all" if prompts appear.
  13. Check if "<path to>\s2client-api" has the directories "include" and "lib". If not create them manually and re-do the previous two steps.
  14. Go to [1] and download Ladder 2017 Season 3.
  15. Extract ONLY THE MAPS! to C:\Program Files (x86)\StarCraft II\Maps\
  16. Confirm that C:\Program Files (x86)\StarCraft II\Maps\InterloperLE.SC2Map exists and NOT for example C:\Program Files (x86)\StarCraft II\Maps\Ladder2017Season3\InterloperLE.SC2Map.

The s2client-api is now installed.

Blank bot[edit]

  1. Download an already prepared blank bot and extract it. For convenience put it in the same directory where you created "s2client-api" (but not inside "s2client-api").
  2. Open "Cryptbot/CryptBot.sln", i.e. double click on it.
  3. Right-click on CryptBot and select Properties in the "Solution Explorer" (left or right side of Visual Studio).
  4. Chose "Configuration: All Configurations".
  5. Then VC++ Directories.
  6. Edit the the "Include Directories" to point to "<path to>\s2client-api\project\include;$(IncludePath)". (maybe already correct.)
  7. Edit the the "Library Directories" to point to "<path to>\s2client-api\project\lib;$(LibraryPath)". (maybe already correct.)
  8. Press apply and then press ok.
  9. In the top row select "Release" and "x64".
  10. In the Solution Open search for the file "CryptbotMain.cpp" and open it.
  11. On line 42 replace the "PleaseSpecify" with for example "Protoss".
  12. If you have not installed SC2 to the default location, adjust the path to the map file in line 29. Remember to use forward slashes ('/') and do not forget the ".SC2Map" at the end.
  13. Build -> Build Solution.
  14. If it says something like "Cannot open include file: 'sc2api/sc2_api.h'" make sure you have done 4. In doubt start again from there.
  15. SDK version missing? Install it via the Visual Studio installer.
  16. Can not open corecrt.h? Go here.
  17. In the top row select "Debug" and "x64".
  18. Build -> Build Solution.
  19. Press "Local Windows Debugger".

If everything was correct till here an instance of SC2 on Interloper LE opens with a Protoss bot that doesn't perform any actions - probes will gather minerals but that is all. You can close SC2 for now. If where you pressed "Local Windows Debugger" is still a red square, press it.

Produce the executable for the ladder manager[edit]

  1. In the top row select "Release" and "x64".
  2. Build -> Build Solution.
  3. Find the executable "CryptBot\x64\Release\CryptBot.exe".
  4. Rename "CryptBot.exe" to <your bot name>.exe.
  5. Upload <your bot name>.exe to

What next?[edit]

Now it is time to write the code. I purposefully let some of the event functions "On..." in the code to give you a first hint what functions are available through the sc2api. I suggest to put a "this->" in the "OnStep()" function and use the Visual Studio auto-completion to skim a little through the available functions. Another place to find hints where to start are the Blizzard examples that are also in your s2client-api folder.

If you want to test and debug the bot, you can let it play against the in-build AI by changing from "Release" to "Debug" and press "Local Windows Debugger". Now you can locally observe your changes to code.


If you have issues building the bot you might need to do 3. and 4. and then change the Windows SDK to 10.

If the bot window opens but closes immediately, open a command line window and start the bot executable from there. The error might tell you what is wrong.

If you have problems do not hesitate to come to the Discord.