Simple StarCraft 2 Python Bot Template To Get Started

Drekken · December 8, 2024, 12:06am

If you’ve watched ProBots and thought, “I’d love to build a bot, but where do I even start?” you’re in the right place. The new python bot template makes it dead simple to jump into StarCraft 2 bot development—even if you’ve never touched game AI before.

This template won’t take you straight to the finals, but it’s a launchpad: fast setup, simple config, and you’ll be mining minerals with your own bot in minutes.

Quick Start

Prerequisites

Python 3.8 or newer
Git
StarCraft II (Battle.net install for Windows, Lutris/Wine for Linux)
Maps: Download the ‘Melee’ pack and put them in your StarCraft II Maps folder.
- If you use a non-standard install location, just set the MAP_PATH in config.py.

Linux with Lutris?

Set these environment variables for best results (replace paths as needed):

export SC2PF=WineLinux
export SC2PATH="/home/YOUR_USERNAME/Games/battlenet/drive_c/Program Files (x86)/StarCraft II/"
export WINE="/home/YOUR_USERNAME/.local/share/lutris/runners/wine/YOUR_WINE_VERSION/bin/wine"

1. Clone the Template

Click Use this template on the GitHub repo.

Clone your new repo:

git clone <your-repository-url>
cd <repository-folder>

2. Set Up Your Environment

Virtual env recommended:

python -m venv venv
# Windows
.\venv\Scripts\activate
# Mac/Linux
source venv/bin/activate

Install dependencies:
```
pip install -r requirements.txt
```

3. Configure Your Bot

Open config.py to:
- Set your bot’s name and race
- Choose map pools and paths
- Set AI opponent race/difficulty
- Pick game mode (realtime/faster)

4. Run Your Bot

python run.py

If setup is correct, SC2 will launch and your bot starts mining minerals.

Customizing and Competing

Edit bot logic: Change bot/bot.py (your main bot file). All code should go in the bot/ folder—it’s what gets packaged for competitions.
Compete: When you’re ready, zip your bot:
```
python create_ladder_zip.py
```
The ready-to-upload file will be in publish/bot.zip.

Upgrade Path: Ares Framework

Want more advanced strategy and control? Upgrade to Ares-sc2 with one command:

python upgrade_to_ares.py

You’ll need to update your bot class and use super() calls in your hooks. Full guide in the repo README.

Questions? Hit reply. Happy bot building.