Simple StarCraft 2 Python Bot Template To Get Started

Drekken · December 8, 2024, 12:06am

If you’ve ever watched an episode of ProBots and thought, “I’d love to build a bot, but where do I even start?” then you’re in the right place. We’ve created an easy-to-use python bot template that will help you dive right into StarCraft 2 bot development.

While this template alone won’t take you to the finals, it’s the perfect launchpad to get you building, testing, and learning how to program a competitive StarCraft 2 bot.

Step 1: Setup Enviroment

Here are a few things you’ll need to set up before getting started:

Prerequisites

Python - Recommended version: Python 3.7.x (though 3.8 should work too).
- Download Python here.
Git - We’ll use Git for version control.
- Download Git here.
StarCraft 2:
- Windows: Install via the Battle.net app.
- Linux: Download the SC2 Linux package here or use Wine with this Lutris setup script.
- For custom install locations or Linux, you may need to set the $SC2PATH environment variable to your SC2 install path.
StarCraft 2 Maps:
- Download StarCraft 2 Maps here.
- For this tutorial, you need at least the Melee pack. Copy the maps into the Maps folder of your SC2 installation (default path: C:\Program Files (x86)\StarCraft II\Maps).

Step 2: Setting Up Your Bot

Head over to our GitHub page and grab the bot template.

1. Create a New Repository

On GitHub, click the green Use this template button (make sure you’re logged in) to create a personal copy of this bot repository.
Clone your repository (open a terminal or PowerShell window, and clone your new repo):
```
git clone <repository_url> <your_folder_name_here>
cd <your_folder_name_here>
```

2. Set Up Your Virtual Environment

Create a virtual environment to keep dependencies organized (use venv for simplicity):
```
python -m venv env
```

Activate it:

Windows:
```
.\env\Scripts\activate
```
MacOS/Linux:
```
source env/bin/activate
```

3. Install Dependencies

Add required Python libraries:
```
pip install -r requirements.txt
```

4. Test Your Bot

Run your bot to check everything is working:
```
python run.py
```

If everything is set up correctly, StarCraft 2 will open, and you’ll see your bot start to mine minerals. You can close the SC2 window to stop your bot.

Step 3: Customizing Your Bot

Naming & Race Selection

Open bot/bot.py, and look for the CompetitiveBot class to specify your bot’s name and race (Terran, Zerg, or Protoss).

Adding Code

Place any new files or code modifications in the bot/ folder. This folder structure is used when creating your bot’s zip file for ladder submission.

Step 4: Competing with Your Bot

When you’re ready to compete, zip up your bot for distribution. Use the following command to package it up:

python create_ladder_zip.py

This will create a bot.zip file in the publish folder. You can upload this file to ProBots competitions or the AI Arena Ladder.