burnysc2 (python-sc2)

The sc2.position module provides several classes for representing spatial data in StarCraft II, including points, sizes, and rectangular areas. These classes are used to define coordinates, dimensions, and regions for unit movement, selection, and area effects.

Available classes:

• Pointlike: A base class for point-based objects.
• Point2: Represents a 2D point (x, y).
• Point3: Represents a 3D point (x, y, z).
• Size: Represents a 2D dimension (width, height).
• Rect: Represents a rectangular area defined by its position and size.

Map organization depends on the type of map being used:

• Official Blizzard maps: Extract into subdirectories within the SC2 maps directory (e.g., install-dir/Maps/Ladder2017Season1/).
• Bot ladder maps (SC2 AI Arena): Extract into the root of the SC2 maps directory (e.g., install-dir/Maps/AcropolisLE.SC2Map) to ensure replays work correctly.

Install the library using pip. Ensure Python 3.9 or newer is installed and that the StarCraft II client is located in the default installation path: C:\Program Files (x86)\StarCraft II.

To install the stable version:

pip install burnysc2

If you need to install a specific branch (e.g., the develop branch) directly from GitHub:

pip install --upgrade --force-reinstall https://github.com/BurnySc2/python-sc2/archive/develop.zip

To ensure your bot uses the correct version of the python-sc2 library and avoids conflicts with outdated system-wide installations, you must bundle the library directly with your bot code.

1. Copy the python-sc2/sc2 folder into your bot's root directory.
2. Update your bot's race configuration in run.py (line 8) and ladderbots.json (line 4).
3. Zip the entire contents of your folder into a <YOUR_BOTS_NAME_HERE>.zip file. Ensure all files are located at the root of the zip archive.

# Example of the required directory structure before zipping:
my_bot_folder/
├── sc2/             # Copied from python-sc2/sc2
├── run.py
├── ladderbots.json
└── requirements.txt

To run StarCraft II on Linux (via Wine or Lutris), you must set specific environment variables. If using Lutris, the default installation path is /home/burny/Games/battlenet/drive_c/Program Files (x86)/StarCraft II/.

SC2PF=WineLinux
WINE=/usr/bin/wine
# Or a wine binary from lutris:
WINE=/home/burny/.local/share/lutris/runners/wine/lutris-4.20-x86_64/bin/wine64
# Default Lutris StarCraftII Installation path:
SC2PATH='/home/burny/Games/battlenet/drive_c/Program Files (x86)/StarCraft II/'

Running Matches

Execute the matches in headless mode using the runner script inside the container:

docker exec -i app uv run python /root/aiarena-client/arenaclient/run_local.py

Retrieving Results and Replays

After the matches finish, copy the data from the container to your host machine for analysis.

Copy results.json:

mkdir -p temp
docker cp app:/root/aiarena-client/arenaclient/proxy/results.json temp/results.json

Copy all replays:

mkdir -p temp/replays
docker cp app:/root/StarCraftII/Replays/. temp/replays

The library detects WSL and defaults to starting the Windows version of StarCraft II.

To force the Linux version, set SC2_WSL_DETECT to "0" in your Python code.

For WSL version 2, you must provide the following environment variables to allow the bot to connect to the Windows host:

• SC2CLIENTHOST: Your Windows IP (find via ipconfig /all in PowerShell).
• SC2SERVERHOST: 0.0.0.0.

import os
# Disable automatic Windows SC2 detection in WSL
os.environ["SC2_WSL_DETECT"] = "0"

# Required for WSL2 connectivity
export SC2CLIENTHOST=<your windows IP>
export SC2SERVERHOST=0.0.0.0

To compete on Sc2AI or Probots:

1. Update ladderbots.json: Ensure the parameters in this file are correctly configured for your bot.
2. Dependencies: Unlike AI Arena, Sc2AI and Probots will automatically pip install any dependencies listed in your requirements.txt file.