README.md

blank-bot

Starter bot for StarCraft II with integrated cpp-sc2.

Table of Contents

• blank-bot
  • Support
  • Build instructions
    • Windows
    • macOS
    • Linux
  • Additional options
    • WSL2 Support
    • Game client version
    • AIArena ladder build
  • Managing CMake dependencies
  • Troubleshooting
    • CMake options don't take effect
    • Build freezes (Linux or macOS)
  • License

Support

Feel free to post questions on the unofficial StarCraft II AI Discord server. Invite Link

Build instructions

🚧 This project requires a compiler with C++17 support.

1. Before proceeding further download the actual map pack.

2. Put the downloaded maps into the Maps folder (create it if the folder doesn't exist):

   • Windows: C:\Program Files\StarCraft II\Maps
   • OS X: /Applications/StarCraft II/Maps
   • Linux: anywhere.

Windows

For building for Windows under WSL2, see WSL2 Support.

1. Install CMake.

2. Download and install Visual Studio (2017 or newer).

3. Get the project.

   git clone git@github.com:cpp-sc2/blank-bot.git

4. Enter the working directory.

   cd blank-bot

5. Create Visual Studio project files in the directory "build". E.g. for Visual Studio 2022:

   cmake -B build -G "Visual Studio 17 2022"

6. Build the project using Visual Studio.

   start build\BlankBot.sln

7. Launch the bot with the specified path to a SC2 map, e.g:

   build\bin\Debug\BlankBot.exe Ladder2019Season3/AcropolisLE.SC2Map

macOS

1. Install CMake.

2. Install XCode.

3. Install XCode command-line tools.

4. Clone the project.

   git clone [email protected]:cpp-sc2/blank-bot.git && cd blank-bot

5. Generate CMake build tree.

   cmake -B build

6. Build the project.

   cmake --build build --parallel $(nproc)

7. Launch the bot with the specified absolute path to a SC2 map, e.g.:

   ./build/bin/BlankBot "/home/alkurbatov/Ladder2019Season3/AcropolisLE.SC2Map"

Linux

1. Install CMake.

2. Install gcc-c++.

3. Install the make utility.

4. Get the project.

   git clone [email protected]:cpp-sc2/blank-bot.git && cd blank-bot

5. Generate CMake build tree.

   cmake -B build

6. Build the project.

   cmake --build build --parallel $(nproc)

7. Launch the bot with the specified absolute path to a SC2 map, e.g.:

   ./build/bin/BlankBot "/home/alkurbatov/Ladder2019Season3/AcropolisLE.SC2Map"

Additional options

WSL2 Support

Cross compiling for Windows under WSL2 is supported through cpp-sc2. See the cpp-sc2 documentation for build requirements. The build flag remains the same, setting -DWSL2_CROSS_COMPILE=ON.

Game client version

By default, the API assumes the latest version of the game client. The assumed version can be found in cmake's output, e.g.:

$ cmake -B build grep 'SC2 version'
Target SC2 version: 5.0.5
...

However, sometimes one may need to compile with an older version of the game, e.g. to play with a Linux build which is always behind the Windows version. It is possible by specifying the game version manually, e.g.:

cmake -B build -DSC2_VERSION=4.10.0

AIArena ladder build

To compile a bot capable to play on the AIArena ladder, configure the project in the following way:

cmake -B build -DBUILD_FOR_LADDER=ON -DSC2_VERSION=4.10.0

Managing CMake dependencies

BlankBot uses the CMake FetchContent module to manage and collect dependencies. To use a version of cpp-sc2 outside of the pinned commit, modify the GIT_REPOSITORY and/or the GIT_TAG in cmake/cpp_sc2.cmake:

...
FetchContent_Declare(
    cpp_sc2
    GIT_REPOSITORY <target-cpp-sc2-git-rep>
    GIT_TAG <git-commit-hash>
)
FetchContent_MakeAvailable(cpp_sc2)
...

With the updated configuration, re-run the build configuration and the dependency will be updated to the new configuration:

cmake -B build

Troubleshooting

CMake options don't take effect

If you see that some of cmake options don't take effect (e.g. project was configured with cmake -B build -DBUILD_FOR_LADDER=ON and a bit later with cmake -B build) remove the build folder or the CMakeCache.txt file, or explicitly re-specify the desired default behavior (e.g. cmake -B build -DBUILD_FOR_LADDER=OFF).

Build freezes (Linux or macOS)

If project compilation freezes, decrease nproc to 1 or more, e.g.:

cmake --build build --parallel $(nproc --ignore=1)

License

Copyright (c) 2021-2024 Alexander Kurbatov

Licensed under the MIT license.