# 快速開始

> 按兩下 start.bat 自動裝好一切，在遠見裡設定好遊戲目錄，開一局看範例 Bot 接管。大約 15 分鐘。

來源: https://war3ai.com/zh-tw/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 把本機模型留在顯示記憶體裡
```

閘道、頭頂氣泡、本機 LLM 也都在遠見「控制中心」裡啟動和停止，不必再找別的指令碼。**徹底停止**：按兩下 `stop.bat`，或者在控制中心右上角點「全部停止」——遊戲實例、AI、閘道、氣泡、本系統使用的本機模型、遠見後台依序全部停止。MCP 伺服器由 Claude 等用戶端管理，不會被停止。

> **設定檔**
>
> `openwar3.json` 由 `start.bat` 和遠見自動寫入，只存本機路徑，不進 git。要修改連接埠、本機 LLM 的位址和模型名稱時，照著 `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/zh-tw/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                                      # 印出 API 目錄
```

## 跑通之後

  - [寫第一個 Bot](https://war3ai.com/zh-tw/docs/first-bot/): 從 10 行的最小 Bot 開始，一步步加上出兵和出擊。
  - [讓 LLM 幫你寫](https://war3ai.com/zh-tw/docs/ai-bot/): 複製提示詞範本，用白話描述打法。

## 自我檢查

```bash
python tools/run_tests.py          # SDK / 參考大腦 / 毫秒層 / 指揮台 / 氣泡 / 範例，每套一個子行程
```

離線測試不需要開遊戲。遠見「控制中心」裡也有環境自檢，能看到各部分有沒有裝好。