Aeolus

A C++ StarCraft II bot playing Protoss. Built from scratch using cpp-sc2.

Table of Contents

• Aeolus
  • About Aeolus
    • Key Features
    • Dependencies
    • Acknowledgements
  • Build instructions
    • Windows
    • macOS
    • Linux
  • Additional options
    • Game client version
    • AIArena ladder build
  • License

About Aeolus

Aeolus is a modern StarCraft II bot framework written in C++, inspired by the modular and scalable design principles of ares-sc2. Named after the Greek keeper of the winds, Aeolus is built to dominate the dynamic environment of StarCraft II with swift decision-making, strategic precision, and efficient resource management.

Key Features

• Behavior-Driven Architecture
  Aeolus employs a behavior executor system to handle core bot actions such as mining, unit production, and combat. This modular approach simplifies development and encourages clean, reusable code.

• Advanced Unit Handling
  Implements algorithms for unit prioritization, distance sorting, and effective micro-management during combat.

• Manager Pattern Design
  Core functionalities are structured around a manager pattern, with every manager implementing the ProcessRequest interface for consistent, scalable logic.

• Utility Toolkit
  A comprehensive set of utility functions for common tasks like sorting units by distance, pathfinding, and filtering.

Dependencies

This project uses the following third-party library:

• nanoflann:
  A lightweight C++ library for KDTree-based nearest neighbor search.
  Licensed under the BSD 2-Clause License. See the thirdparty/nanoflann/LICENSE.txt file for details.

• Eigen:
  A C++ template library for linear algebra, including matrices, vectors, numerical solvers, and related algorithms.
  Licensed under the Mozilla Public License 2.0. See the COPYING.MPL2 file or visit Eigen's GitHub repository for more details.

Acknowledgements

Aeolus draws inspiration from ares-sc2, an excellent framework by Rasper. Special thanks to the ares-sc2 project for setting the bar for StarCraft II bot development and serving as a foundation for learning and innovation.

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

1. Install CMake.

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

3. Get the project.

   git clone git@github.com:hammer-hao/aeolus.git

4. Enter the working directory.

   cd aeolus

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\Aeolus.sln

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

   build\bin\Debug\Aeolus.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]:hammer-hao/aeolus.git && cd Aeolus

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/Aeolus "/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]:hammer-hao/aeolus.git && cd aeolus

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/Aeolus "/home/alkurbatov/Ladder2019Season3/AcropolisLE.SC2Map"

Additional options

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

License

Licensed under the MIT license.