[](https://github.com/BurnySc2/python-sc2/actions)
[](https://codecov.io/gh/BurnySc2/python-sc2)
# A StarCraft II API Client for Python 3
An easy-to-use library for writing AI Bots for StarCraft II in Python 3. The ultimate goal is simplicity and ease of use, while still preserving all functionality. A really simple worker rush bot should be no more than twenty lines of code, not two hundred. However, this library intends to provide both high and low level abstractions.
**This library (currently) covers only the raw scripted interface.** At this time I don't intend to add support for graphics-based interfaces.
The [documentation can be found here](https://burnysc2.github.io/python-sc2/docs/index.html).
For bot authors, looking directly at the files in the [sc2 folder](/sc2) can also be of benefit: bot_ai.py, unit.py, units.py, client.py, game_info.py and game_state.py. Most functions in those files have docstrings, example usages and type hinting.
I am planning to change this fork more radically than the main repository, for bot performance benefits and to add functions to help new bot authors. This may break older bots in the future, however I try to add deprecation warnings to give a heads up notification. This means that the [video tutorial made by sentdex](https://pythonprogramming.net/starcraft-ii-ai-python-sc2-tutorial/) is outdated and does no longer directly work with this fork.
For a list of ongoing changes and differences to the main repository of Dentosal, [check here](https://github.com/BurnySc2/python-sc2/issues/4).
## Installation
By installing this library you agree to be bound by the terms of the [AI and Machine Learning License](http://blzdistsc2-a.akamaihd.net/AI_AND_MACHINE_LEARNING_LICENSE.html).
For this fork, you'll need Python 3.10 or newer.
Install the pypi package:
```
pip install --upgrade burnysc2
```
or directly from develop branch:
```
pip install --upgrade --force-reinstall https://github.com/BurnySc2/python-sc2/archive/develop.zip
```
Both commands will use the `sc2` library folder, so you will not be able to have Dentosal's and this fork installed at the same time, unless you use virtual environments.
## StarCraft II
You'll need a StarCraft II executable. If you are running Windows or macOS, just install SC2 from [blizzard app](https://starcraft2.com/).
### Linux installation
You can install StarCraft II on Linux with [Wine](https://www.winehq.org/), [Lutris](https://lutris.net/games/battlenet/) or even the [Linux binary](https://github.com/Blizzard/s2client-proto#downloads), but the latter is headless so you cannot actually see the game.
Starcraft II can be directly installed from Battlenet once it is downloaded with Lutris.
By default, it will be installed here:
```
/home/burny/Games/battlenet/drive_c/Program Files (x86)/StarCraft II/
```
Next, set the following environment variables (either globally or within your development environment, e.g. Pycharm: `Run -> Edit Configurations -> Environment Variables`):
```
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/'
```
### WSL
When running WSL in Windows, python-sc2 detects WSL by default and starts Windows Starcraft 2 instead of Linux Starcraft 2.
If you wish to instead have the game played in Linux, you can disable this behavior by setting `SC2_WSL_DETECT`
environment variable to "0". You can do this inside python with the following code:
```py
import os
os.environ["SC2_WSL_DETECT"] = "0"
```
WSL version 1 should not require any configuration. You may be asked to allow Python through your firewall.
When running WSL version 2 you need to supply the following environment variables so that your bot can connect:
```
SC2CLIENTHOST=<your windows IP>
SC2SERVERHOST=0.0.0.0
```
If you are adding these to your .bashrc, you may need to export your environment variables by adding:
```sh
export SC2CLIENTHOST
export SC2SERVERHOST
```
You can find your Windows IP using `ipconfig /all` from `PowerShell.exe` or `CMD.exe`.
## Maps
You will need maps to run the library.
#### Official maps
Official Blizzard map downloads are available from [Blizzard/s2client-proto](https://github.com/Blizzard/s2client-proto#downloads).
Extract these maps into their respective *subdirectories* in the SC2 maps directory.
e.g. `install-dir/Maps/Ladder2017Season1/`
#### Bot ladder maps
Maps that are run on the [SC2 AI Ladder](http://sc2ai.net/) and [SC2 AI Arena](https://aiarena.net/) can be downloaded [from the sc2ai wiki](http://wiki.sc2ai.net/Ladder_Maps) and [the aiarena wiki](https://aiarena.net/wiki/bot-development/getting-started/#wiki-toc-maps).
**Extract these maps into the *root* of the SC2 maps directory** (otherwise ladder replays won't work).
e.g. `install-dir/Maps/AcropolisLE.SC2Map`
### Running
After installing the library, a StarCraft II executable, and some maps, you're ready to get started. Simply run a bot file to fire up an instance of StarCraft II with the bot running. For example:
```sh
python examples/protoss/cannon_rush.py
```
## Example
As promised, worker rush in less than twenty lines:
```python
from sc2 import maps
from sc2.player import Bot, Computer
from sc2.main import run_game
from sc2.data import Race, Difficulty
from sc2.bot_ai import BotAI
class WorkerRushBot(BotAI):
async def on_step(self, iteration: int):
if iteration == 0:
for worker in self.workers:
worker.attack(self.enemy_start_locations[0])
run_game(maps.get("Abyssal Reef LE"), [
Bot(Race.Zerg, WorkerRushBot()),
Computer(Race.Protoss, Difficulty.Medium)
], realtime=True)
```
This is probably the simplest bot that has any realistic chances of winning the game. I have ran it against the medium AI a few times, and once in a while, it wins.
You can find more examples in the [`examples/`](/examples) folder.
## API Configuration Options
The API supports a number of options for configuring how it operates.
### `unit_command_uses_self_do`
Set this to 'True' if your bot is issueing commands using `self.do(Unit(Ability, Target))` instead of `Unit(Ability, Target)`.
```python
class MyBot(BotAI):
def __init__(self):
self.unit_command_uses_self_do = True
```
### `raw_affects_selection`
Setting this to true improves bot performance by a little bit.
```python
class MyBot(BotAI):
def __init__(self):
self.raw_affects_selection = True
```
### `distance_calculation_method`
The distance calculation method:
- 0 for raw python
- 1 for scipy pdist
- 2 for scipy cdist
```python
class MyBot(BotAI):
def __init__(self):
self.distance_calculation_method: int = 2
```
### `game_step`
On game start or in any frame actually, you can set the game step. This controls how often your bot's `step` method is called.
__Do not set this in the \_\_init\_\_ function as the client will not have been initialized yet!__
```python
class MyBot(BotAI):
def __init__(self):
pass # don't set it here!
async def on_start(self):
self.client.game_step: int = 2
```
## Community - Help and support
You have questions but don't want to create an issue? Join the [Starcraft 2 AI Discord server](https://discordapp.com/invite/zXHU4wM) or [aiarena.net Discord server](https://discord.gg/yDBzbtC). Questions about this repository can be asked in text channel #python. There are discussions and questions about SC2 bot programming and this repository every day.
## Bug reports, feature requests and ideas
If you have any issues, ideas or feedback, please create [a new issue](https://github.com/BurnySc2/python-sc2/issues/new). Pull requests are also welcome!
## Contributing & style guidelines
Git commit messages use [imperative-style messages](https://stackoverflow.com/a/3580764/2867076), start with capital letter and do not have trailing commas.
To run pre-commit hooks (which run autoformatting and autosort imports) you can run
```sh
uv run pre-commit install
uv run pre-commit run --all-files --hook-stage push
```
Raw data
{
"_id": null,
"home_page": null,
"name": "burnysc2",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.13,>=3.9",
"maintainer_email": null,
"keywords": "StarCraft, StarCraft 2, StarCraft II, AI, Bot",
"author": null,
"author_email": "BurnySc2 <gamingburny@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/0d/0f/f71f01a62d878243d106294a23de6a785db34351d3e55ff0c9b8bf400182/burnysc2-7.0.5.tar.gz",
"platform": null,
"description": "[](https://github.com/BurnySc2/python-sc2/actions)\n[](https://codecov.io/gh/BurnySc2/python-sc2)\n\n# A StarCraft II API Client for Python 3\n\nAn easy-to-use library for writing AI Bots for StarCraft II in Python 3. The ultimate goal is simplicity and ease of use, while still preserving all functionality. A really simple worker rush bot should be no more than twenty lines of code, not two hundred. However, this library intends to provide both high and low level abstractions.\n\n**This library (currently) covers only the raw scripted interface.** At this time I don't intend to add support for graphics-based interfaces.\n\nThe [documentation can be found here](https://burnysc2.github.io/python-sc2/docs/index.html).\nFor bot authors, looking directly at the files in the [sc2 folder](/sc2) can also be of benefit: bot_ai.py, unit.py, units.py, client.py, game_info.py and game_state.py. Most functions in those files have docstrings, example usages and type hinting.\n\nI am planning to change this fork more radically than the main repository, for bot performance benefits and to add functions to help new bot authors. This may break older bots in the future, however I try to add deprecation warnings to give a heads up notification. This means that the [video tutorial made by sentdex](https://pythonprogramming.net/starcraft-ii-ai-python-sc2-tutorial/) is outdated and does no longer directly work with this fork.\n\nFor a list of ongoing changes and differences to the main repository of Dentosal, [check here](https://github.com/BurnySc2/python-sc2/issues/4).\n\n## Installation\n\nBy installing this library you agree to be bound by the terms of the [AI and Machine Learning License](http://blzdistsc2-a.akamaihd.net/AI_AND_MACHINE_LEARNING_LICENSE.html).\n\nFor this fork, you'll need Python 3.10 or newer.\n\nInstall the pypi package:\n```\npip install --upgrade burnysc2\n```\nor directly from develop branch:\n```\npip install --upgrade --force-reinstall https://github.com/BurnySc2/python-sc2/archive/develop.zip\n```\nBoth commands will use the `sc2` library folder, so you will not be able to have Dentosal's and this fork installed at the same time, unless you use virtual environments.\n\n## StarCraft II\nYou'll need a StarCraft II executable. If you are running Windows or macOS, just install SC2 from [blizzard app](https://starcraft2.com/).\n\n### Linux installation\n\nYou can install StarCraft II on Linux with [Wine](https://www.winehq.org/), [Lutris](https://lutris.net/games/battlenet/) or even the [Linux binary](https://github.com/Blizzard/s2client-proto#downloads), but the latter is headless so you cannot actually see the game.\nStarcraft II can be directly installed from Battlenet once it is downloaded with Lutris.\nBy default, it will be installed here:\n```\n/home/burny/Games/battlenet/drive_c/Program Files (x86)/StarCraft II/\n```\nNext, set the following environment variables (either globally or within your development environment, e.g. Pycharm: `Run -> Edit Configurations -> Environment Variables`):\n\n```\nSC2PF=WineLinux\nWINE=/usr/bin/wine\n# Or a wine binary from lutris:\n# WINE=/home/burny/.local/share/lutris/runners/wine/lutris-4.20-x86_64/bin/wine64\n# Default Lutris StarCraftII Installation path:\nSC2PATH='/home/burny/Games/battlenet/drive_c/Program Files (x86)/StarCraft II/'\n```\n\n### WSL\n\nWhen running WSL in Windows, python-sc2 detects WSL by default and starts Windows Starcraft 2 instead of Linux Starcraft 2.\nIf you wish to instead have the game played in Linux, you can disable this behavior by setting `SC2_WSL_DETECT`\nenvironment variable to \"0\". You can do this inside python with the following code:\n```py\nimport os\nos.environ[\"SC2_WSL_DETECT\"] = \"0\"\n``` \n\nWSL version 1 should not require any configuration. You may be asked to allow Python through your firewall.\n\nWhen running WSL version 2 you need to supply the following environment variables so that your bot can connect:\n\n```\nSC2CLIENTHOST=<your windows IP>\nSC2SERVERHOST=0.0.0.0\n```\n\nIf you are adding these to your .bashrc, you may need to export your environment variables by adding:\n```sh\nexport SC2CLIENTHOST\nexport SC2SERVERHOST\n```\n\nYou can find your Windows IP using `ipconfig /all` from `PowerShell.exe` or `CMD.exe`.\n\n## Maps\nYou will need maps to run the library.\n\n#### Official maps\nOfficial Blizzard map downloads are available from [Blizzard/s2client-proto](https://github.com/Blizzard/s2client-proto#downloads). \nExtract these maps into their respective *subdirectories* in the SC2 maps directory. \ne.g. `install-dir/Maps/Ladder2017Season1/`\n\n#### Bot ladder maps\nMaps that are run on the [SC2 AI Ladder](http://sc2ai.net/) and [SC2 AI Arena](https://aiarena.net/) can be downloaded [from the sc2ai wiki](http://wiki.sc2ai.net/Ladder_Maps) and [the aiarena wiki](https://aiarena.net/wiki/bot-development/getting-started/#wiki-toc-maps). \n**Extract these maps into the *root* of the SC2 maps directory** (otherwise ladder replays won't work). \ne.g. `install-dir/Maps/AcropolisLE.SC2Map`\n\n### Running\n\nAfter installing the library, a StarCraft II executable, and some maps, you're ready to get started. Simply run a bot file to fire up an instance of StarCraft II with the bot running. For example:\n\n```sh\npython examples/protoss/cannon_rush.py\n```\n\n## Example\n\nAs promised, worker rush in less than twenty lines:\n\n```python\nfrom sc2 import maps\nfrom sc2.player import Bot, Computer\nfrom sc2.main import run_game\nfrom sc2.data import Race, Difficulty\nfrom sc2.bot_ai import BotAI\n\nclass WorkerRushBot(BotAI):\n async def on_step(self, iteration: int):\n if iteration == 0:\n for worker in self.workers:\n worker.attack(self.enemy_start_locations[0])\n\nrun_game(maps.get(\"Abyssal Reef LE\"), [\n Bot(Race.Zerg, WorkerRushBot()),\n Computer(Race.Protoss, Difficulty.Medium)\n], realtime=True)\n```\n\nThis is probably the simplest bot that has any realistic chances of winning the game. I have ran it against the medium AI a few times, and once in a while, it wins.\n\nYou can find more examples in the [`examples/`](/examples) folder.\n\n## API Configuration Options\n\nThe API supports a number of options for configuring how it operates.\n\n### `unit_command_uses_self_do`\nSet this to 'True' if your bot is issueing commands using `self.do(Unit(Ability, Target))` instead of `Unit(Ability, Target)`.\n```python\nclass MyBot(BotAI):\n def __init__(self):\n self.unit_command_uses_self_do = True\n```\n\n### `raw_affects_selection`\nSetting this to true improves bot performance by a little bit.\n```python\nclass MyBot(BotAI):\n def __init__(self):\n self.raw_affects_selection = True\n```\n\n### `distance_calculation_method`\nThe distance calculation method:\n- 0 for raw python\n- 1 for scipy pdist\n- 2 for scipy cdist\n```python\nclass MyBot(BotAI):\n def __init__(self):\n self.distance_calculation_method: int = 2\n```\n\n### `game_step`\nOn game start or in any frame actually, you can set the game step. This controls how often your bot's `step` method is called. \n__Do not set this in the \\_\\_init\\_\\_ function as the client will not have been initialized yet!__\n```python\nclass MyBot(BotAI):\n def __init__(self):\n pass # don't set it here!\n\n async def on_start(self):\n self.client.game_step: int = 2\n```\n\n## Community - Help and support\n\nYou have questions but don't want to create an issue? Join the [Starcraft 2 AI Discord server](https://discordapp.com/invite/zXHU4wM) or [aiarena.net Discord server](https://discord.gg/yDBzbtC). Questions about this repository can be asked in text channel #python. There are discussions and questions about SC2 bot programming and this repository every day.\n\n## Bug reports, feature requests and ideas\n\nIf you have any issues, ideas or feedback, please create [a new issue](https://github.com/BurnySc2/python-sc2/issues/new). Pull requests are also welcome!\n\n\n## Contributing & style guidelines\n\nGit commit messages use [imperative-style messages](https://stackoverflow.com/a/3580764/2867076), start with capital letter and do not have trailing commas.\n\nTo run pre-commit hooks (which run autoformatting and autosort imports) you can run\n```sh\nuv run pre-commit install\nuv run pre-commit run --all-files --hook-stage push\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "A StarCraft II API Client for Python 3",
"version": "7.0.5",
"project_urls": {
"Documentation": "https://burnysc2.github.io/python-sc2",
"Repository": "https://github.com/Burnysc2/python-sc2"
},
"split_keywords": [
"starcraft",
" starcraft 2",
" starcraft ii",
" ai",
" bot"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c8149fa51d3fd7c8608bdb8ad7612dda90767bb4ca0f52fa1bc06456bb28dd5d",
"md5": "565873d26cea88d400bce3ca91b4aa96",
"sha256": "cab015e08cc6715aef7deb0436dcd135b8e027065aa3f8f050e8f686afa36285"
},
"downloads": -1,
"filename": "burnysc2-7.0.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "565873d26cea88d400bce3ca91b4aa96",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.13,>=3.9",
"size": 175201,
"upload_time": "2025-01-05T20:19:20",
"upload_time_iso_8601": "2025-01-05T20:19:20.158369Z",
"url": "https://files.pythonhosted.org/packages/c8/14/9fa51d3fd7c8608bdb8ad7612dda90767bb4ca0f52fa1bc06456bb28dd5d/burnysc2-7.0.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "0d0ff71f01a62d878243d106294a23de6a785db34351d3e55ff0c9b8bf400182",
"md5": "f346b47eb6aca94aceb1db6065721e09",
"sha256": "f41077c3a94c806c54ecbf43a39ca8ee1679de6d56ca1b75b4323721aae1b454"
},
"downloads": -1,
"filename": "burnysc2-7.0.5.tar.gz",
"has_sig": false,
"md5_digest": "f346b47eb6aca94aceb1db6065721e09",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.13,>=3.9",
"size": 174030,
"upload_time": "2025-01-05T20:19:22",
"upload_time_iso_8601": "2025-01-05T20:19:22.561942Z",
"url": "https://files.pythonhosted.org/packages/0d/0f/f71f01a62d878243d106294a23de6a785db34351d3e55ff0c9b8bf400182/burnysc2-7.0.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-05 20:19:22",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Burnysc2",
"github_project": "python-sc2",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "burnysc2"
}
JSON
