适用于 Python 3 的星际争霸 II API 客户端库

这是一个易于使用的 Python 3 库，用于编写星际争霸 II 的 AI 战术机器人。其最终目标是简化开发流程并提高易用性，同时保留所有功能。一个非常简单的工人rush战术机器人代码不应超过二十行，而不是两百行。然而，该库旨在提供高级和低级抽象。

目前，此库仅覆盖原始脚本接口。 截至当前，我无意添加对基于图形界面的支持。

文档在此。对于机器人开发者来说，直接查看 sc2 文件夹 中的文件也会有所帮助：bot_ai.py、unit.py、units.py、client.py、game_info.py 和 game_state.py。这些文件中的大多数函数都带有文档字符串、示例用法和类型提示。

我计划对这个分支进行比主仓库更彻底的改动，以提升机器人性能并增加帮助新手开发者的新功能。这可能会在未来破坏旧版机器人，不过我会尽量加入弃用警告以便提前通知。这意味着由 sentdex 制作的视频教程已经过时，并且不再直接适用于此分支。

有关正在进行的更改以及与 Dentosal 主仓库的区别列表，请参见此处。

安装

安装本库即表示您同意受AI与机器学习许可协议条款约束。

对于此分支，您需要 Python 3.9 或更高版本。

安装 pypi 包：

pip install --upgrade burnysc2

或直接从 develop 分支安装：

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

这两个命令都会使用 sc2 库文件夹，因此除非您使用虚拟环境，否则无法同时安装 Dentosal 的版本和此分支。

星际争霸 II

您需要一个星际争霸 II 可执行文件。如果您使用 Windows 或 macOS，只需从 暴雪应用安装 SC2 即可。

Linux 安装

您可以通过 Wine、Lutris，甚至使用 Linux 二进制文件在 Linux 上安装星际争霸 II，但后者是无头模式，您将无法看到游戏画面。 一旦通过 Lutris 下载了游戏，就可以直接从 Battlenet 安装星际争霸 II。 默认情况下，它会被安装在这里：

/home/burny/Games/battlenet/drive_c/Program Files (x86)/StarCraft II/

接下来，设置以下环境变量（可以是全局设置，也可以在您的开发环境中设置，例如 Pycharm：运行 -> 编辑配置 -> 环境变量）：

SC2PF=WineLinux
WINE=/usr/bin/wine
# 或者来自 lutris 的 wine 二进制文件：
# WINE=/home/burny/.local/share/lutris/runners/wine/lutris-4.20-x86_64/bin/wine64
# 默认的 Lutris 星际争霸 II 安装路径：
SC2PATH='/home/burny/Games/battlenet/drive_c/Program Files (x86)/StarCraft II/'

WSL

在 Windows 中运行 WSL 时，python-sc2 默认会检测到 WSL 并启动 Windows 版星际争霸 II，而不是 Linux 版。如果您希望游戏在 Linux 中运行，可以将 SC2_WSL_DETECT 环境变量设置为“0”。您可以在 Python 中使用以下代码完成此操作：

import os
os.environ["SC2_WSL_DETECT"] = "0"

WSL 第 1 版通常不需要任何配置。您可能需要允许 Python 通过防火墙。

当您运行 WSL 第 2 版时，需要设置以下环境变量，以便您的机器人能够连接：

SC2CLIENTHOST=<您的 Windows IP>
SC2SERVERHOST=0.0.0.0

如果您将这些变量添加到 .bashrc 文件中，可能还需要导出环境变量：

export SC2CLIENTHOST
export SC2SERVERHOST

您可以通过 PowerShell.exe 或 CMD.exe 使用 ipconfig /all 查找您的 Windows IP 地址。

地图

您需要地图才能运行该库。

官方地图

官方暴雪地图下载可从 Blizzard/s2client-proto 获取。 请将这些地图解压到 SC2 地图目录下的相应子目录中。 例如：install-dir/Maps/Ladder2017Season1/

机器人联赛地图

在 SC2 AI Arena 联赛上使用的地图可以从 SC2 AI Arena Wiki 下载。 请将这些地图解压到 SC2 地图目录的根目录中（否则联赛回放将无法正常工作）。 例如：install-dir/Maps/AcropolisLE.SC2Map

运行

在安装好库、星际争霸 II 可执行文件和一些地图后，您就可以开始使用了。只需运行一个机器人文件即可启动一个带有机器人运行的星际争霸 II 实例。例如：

python examples/protoss/cannon_rush.py

示例

正如承诺的那样，不到二十行代码就能实现工人rush战术：

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)

这可能是最简单的、有一定胜算的机器人之一。我曾多次将其与中级 AI 对战，偶尔也能获胜。

更多示例可在 examples/ 文件夹中找到。

API 配置选项

API 支持多种配置选项来调整其运行方式。

unit_command_uses_self_do

如果您的机器人使用 self.do(Unit(Ability, Target)) 而不是 Unit(Ability, Target) 来发出命令，请将此选项设置为“True”。

class MyBot(BotAI):
    def __init__(self):
        self.unit_command_uses_self_do = True

raw_affects_selection

将此选项设置为“真”可以略微提升机器人性能。

class MyBot(BotAI):
    def __init__(self):
        self.raw_affects_selection = True

distance_calculation_method

距离计算方法：

• 0 表示原生 Python
• 1 表示 scipy pdist
• 2 表示 scipy cdist

class MyBot(BotAI):
    def __init__(self):
        self.distance_calculation_method: int = 2

game_step

在游戏开始时，或者在任何一帧中，你都可以设置游戏步长。这决定了你的机器人 step 方法被调用的频率。
请勿在 __init__ 函数中设置此值，因为此时客户端尚未初始化！

class MyBot(BotAI):
    def __init__(self):
        pass  # 不要在这里设置！

    async def on_start(self):
        self.client.game_step: int = 2

社区 - 帮助与支持

如果你有疑问但又不想创建问题？欢迎加入 SC2 AI Arena Discord 服务器。关于本仓库的问题可以在 #python 文本频道中提出。每天都有关于 SC2 机器人编程以及本仓库的讨论和提问。

错误报告、功能请求和想法

如果你有任何问题、想法或反馈，请创建一个新的 issue。我们也欢迎提交 pull request！

贡献与代码风格指南

Git 提交信息应采用【祈使句式】（参考：stackoverflow），首字母大写且不使用结尾逗号。

要运行预提交钩子（用于自动格式化和自动排序导入语句），可以执行以下命令：

uv run pre-commit install
uv run pre-commit run --all-files --hook-stage pre-push

python-sc2 快速上手指南

python-sc2 是一个用于编写《星际争霸 II》(StarCraft II) AI 机器人的 Python 3 库。它旨在提供简单易用的接口，同时保留完整的功能，让开发者能够快速构建从基础到高级的博弈策略。

环境准备

在开始之前，请确保满足以下系统和软件要求：

• 操作系统: Windows, macOS 或 Linux (Linux 用户需配置 Wine 或使用 WSL)。
• Python 版本: Python 3.9 或更高版本。
• 游戏本体: 必须安装《星际争霸 II》客户端。
  • Windows/macOS: 通过暴雪战网 (Battle.net) 直接安装。
  • Linux: 推荐使用 Lutris 配合 Wine 安装，或使用无头模式的 Linux 二进制文件。
• 游戏地图: 需要下载官方地图包并解压至游戏目录下的 Maps 文件夹中。
  • 官方地图下载地址：Blizzard/s2client-proto
  • 天梯地图需解压至 Maps 根目录。

注意：安装此库即表示您同意遵守 AI 和机器学习许可协议。

安装步骤

推荐使用 pip 进行安装。由于网络原因，国内开发者建议使用国内镜像源（如清华源或阿里源）以加速下载。

方式一：安装稳定版 (PyPI)

pip install --upgrade burnysc2 -i https://pypi.tuna.tsinghua.edu.cn/simple

方式二：安装开发版 (GitHub Develop 分支)

如果您需要最新的功能修复或特性，可以直接从 GitHub 安装：

pip install --upgrade --force-reinstall https://github.com/BurnySc2/python-sc2/archive/develop.zip -i https://pypi.tuna.tsinghua.edu.cn/simple

提示: 该库使用 sc2 作为包名。如果您之前安装过其他 forks (如 Dentosal 版本)，请先卸载或使用虚拟环境，以免冲突。

基本使用

以下是一个最简单的“工人 Rush"机器人示例，代码不到 20 行。该脚本会启动游戏，控制所有工人在游戏开始时直接攻击敌方出生点。

创建一个名为 worker_rush.py 的文件，填入以下代码：

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)

运行机器人

确保游戏未运行，然后在终端执行：

python worker_rush.py

脚本将自动启动《星际争霸 II》并加载指定地图，您的机器人将作为虫族 (Zerg) 与中等难度的电脑 (Protoss) 进行对战。

更多示例代码请参考项目仓库中的 examples/ 文件夹。