# 快速开始

> 双击 start.bat 自动装好一切，在远见里设好游戏目录，起一局看示例 Bot 接管。大约 15 分钟。

来源: https://war3ai.com/docs/quickstart/

## 你需要

| | 要求 | 说明 |
|---|---|---|
| 系统 | Windows 10 / 11，64 位 | 目前只支持 Windows |
| 游戏 | 魔兽争霸 III **1.27a**（冰封王座，`Game.dll` 1.27.0.52240） | 你自己合法拥有的客户端；不修改磁盘上的任何游戏文件 |

**别的都不用先装。** `start.bat` 只下载一样东西：Python 3.13（官方便携包，约 14 MB），放在仓库的 `bin\env\` 里，不要管理员权限、不改系统 PATH，国内网络自动换镜像；电脑上已经有能用的 Python 就直接用。PowerShell 用 Windows 自带的；远见的网页随仓库提供编好的，不用 Node.js。

## 安装

1. **拿到代码**

   ```bash
   git clone https://github.com/OPENXXAI/OpenWar3AI.git
   ```

   或者[下载压缩包](https://github.com/OPENXXAI/OpenWar3AI/archive/refs/heads/main.zip)解压。运行时（注入 DLL 和启动器）随仓库一起提供，不用另外下载。

2. **双击 `start.bat`**

   第一次它会自己：

   - 下载 Python 3.13；
   - 安装 Python 包，核对运行时文件后装好；
   - 下载 AMAI 生成参考大脑要用的战略数据（AMAI 为自定义许可，生成物不进 git；失败只影响参考大脑）；
   - 打开远见的首页「控制中心」 `http://127.0.0.1:8866`。

   每一步都打印结果，没成功的那一步会告诉你怎么补。以后每次双击只做一两秒的检查就打开远见。

   黑色窗口几秒后会自己关掉：远见在后台继续运行，关掉浏览器也不会停。

3. **在控制中心设置游戏目录**

   控制中心最上面可以「自动查找」，也可以「浏览…」自己选魔兽争霸 III 的目录。远见会检查游戏版本，并**从你自己的游戏里提取数据**（单位表、技能、物品、克制表……暴雪的文件不随代码分发）。

   版本不是 1.27a 时会提示你。地图和下一局的设置都相对这个目录（`<游戏目录>\Maps` 下所有文件夹的地图都能选）；以后换目录在「设置」页。

4. **起一局，让示例 Bot 接管**

   最省事的是在远见「实例与开局」页勾一个实例号，选好 AI 方案点「开始测试」。也可以用命令行：

   ```bash
   python tools/play.py --bot brains/examples/hello_bot.py
   ```

   这条命令会：起一个游戏实例、注入运行时、自动开局，然后拉起 Bot。**看到农民去采矿、大厅开始造农民，就成功了。**

   命令里的 `python` 用 `openwar3.json` 里记的那个；`start.bat` 自己装的在 `bin\env\python\python.exe`。

## start.bat 和 stop.bat

```bash
start.bat              # 部署检查 + 打开远见
start.bat setup        # 完整检查：重装 Python 包、重试 AMAI
start.bat restart      # 只重启远见后台（游戏和各服务不受影响）
start.bat node         # 顺带装一份 Node.js（只有预览官网时要它，平时用不着）
start.bat 5 6          # 顺带开始 5、6 号实例的测试（游戏 + 参考大脑）
stop.bat               # 彻底停止全部；stop.bat --keep-llm 把本地模型留在显存里
```

网关、头顶气泡、本地大模型也都在远见「控制中心」里起停，不用再找别的脚本。**彻底停止**：双击 `stop.bat`，或者在控制中心右上角点「全部停止」——游戏实例、AI、网关、气泡、本系统用的本地模型、远见后台依次全停。MCP 服务器归 Claude 等客户端管，不会被停。

> **配置文件**
>
> `openwar3.json` 由 `start.bat` 和远见自动写，只存本机路径，不进 git。要改端口、本地大模型的地址和模型名时，照 `openwar3.example.json` 只写和它不同的项。

## play.py 的参数

```bash
python tools/play.py --bot my_bot.py --inst 9 --race 2 --enemy-race 1 --difficulty 3 --speed 200
python tools/play.py --bot my_bot.py --inst 9 --attach      # 游戏已经开着，只接 Bot
python tools/play.py --bot my_bot.py --fair                 # 公平模式：只看得见视野里的东西
```

| 参数 | 默认 | 说明 |
|---|---|---|
| `--bot` | 必填 | Bot 文件路径（文件里要有一个 `Bot` 的子类） |
| `--inst` | `9` | 实例号。别和正在跑的实例撞号（远见「实例与开局」页能看到哪些号在用） |
| `--race` | `1` | 我方种族：1 人族、2 兽族、3 亡灵、4 暗夜精灵 |
| `--enemy-race` | `0` | 对手种族 |
| `--difficulty` | `2` | 电脑对手难度：2 简单、3 普通、4 疯狂 |
| `--speed` | `100` | 游戏倍速（百分比，200 = 2 倍速） |
| `--map` | 配置里的 `default_map` | 地图 |
| `--attach` | | 不起游戏，只接到已经在跑的实例 |
| `--hz` | `5` | 每秒调用 `on_tick` 几次 |
| `--minutes` | `60` | 最多跑多少分钟（墙钟） |
| `--fair` | | [公平模式](https://war3ai.com/docs/fair-mode/) |
| `--player` | | 以几号玩家的身份指挥（AI 对 AI 时用） |

> **注意**
>
> 别用 `--minimize` 起游戏：**窗口最小化时游戏模拟是停着的**（时钟不走），Bot 会一直等不到进局。

也可以不经 `play.py`，直接用 SDK 的命令行接到一个已经在跑的实例：

```bash
python -m openwar3 run brains/examples/hello_bot.py --inst 5     # 跑 Bot
python -m openwar3 status --inst 5                              # 连一下，打印快照 / 快车道状态
python -m openwar3 catalog                                      # 打印接口目录
```

## 跑通之后

  - [写第一个 Bot](https://war3ai.com/docs/first-bot/): 从 10 行的最小 Bot 开始，一步步加上造兵和出击。
  - [让大模型替你写](https://war3ai.com/docs/ai-bot/): 复制提示词模板，用大白话描述打法。

## 自检

```bash
python tools/run_tests.py          # SDK / 参考大脑 / 毫秒层 / 指挥台 / 气泡 / 示例，每套一个子进程
```

离线测试不需要开游戏。远见「控制中心」里也有环境自检，能看到各部分装好了没有。