快速開始 - War3AI

你需要

	需求	說明
系統	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。

安裝

取得程式碼
```
git clone https://github.com/OPENXXAI/OpenWar3AI.git
```
或者下載壓縮檔後解壓縮。執行環境（注入 DLL 和啟動器）隨儲存庫一起提供，不用另外下載。
按兩下 start.bat

第一次執行時它會自己：
- 下載 Python 3.13；
- 安裝 Python 套件，核對執行環境檔案後裝好；
- 下載 AMAI，產生參考大腦要用的戰略資料（AMAI 採自訂授權，產生的檔案不進 git；失敗只影響參考大腦）；
- 開啟遠見的首頁「控制中心」 http://127.0.0.1:8866。
每一步都會印出結果，沒成功的那一步會告訴你怎麼補上。之後每次按兩下只做一兩秒的檢查，就會開啟遠見。

黑色視窗幾秒後會自己關閉：遠見在背景繼續執行，關掉瀏覽器也不會停止。
在控制中心設定遊戲目錄

控制中心最上方可以「自動查找」，也可以「瀏覽…」自己選擇魔獸爭霸 III 的目錄。遠見會檢查遊戲版本，並從你自己的遊戲裡擷取資料（單位表、技能、物品、克制表……暴雪的檔案不隨程式碼散布）。

版本不是 1.27a 時會提示你。地圖和下一局的設定都以這個目錄為準（<遊戲目錄>\Maps 下所有資料夾的地圖都能選）；之後要換目錄，請到「設定」頁。
開一局，讓範例 Bot 接管

最省事的方法是在遠見「實例與開局」頁勾選一個實例編號，選好 AI 方案後點「開始測試」。也可以用命令列：
```
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

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 的參數

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`		公平模式
`--player`		以幾號玩家的身分指揮（AI 對 AI 時使用）

別用 --minimize 啟動遊戲：視窗最小化時遊戲模擬是停住的（時鐘不走），Bot 會一直等不到對局開始。

也可以不經過 play.py，直接用 SDK 的命令列接上一個已經在跑的實例：

python -m openwar3 run brains/examples/hello_bot.py --inst 5     # 執行 Bot
python -m openwar3 status --inst 5                              # 連線一下，印出快照 / 快車道狀態
python -m openwar3 catalog                                      # 印出 API 目錄

跑通之後

寫第一個 Bot 從 10 行的最小 Bot 開始，一步步加上出兵和出擊。讓 LLM 幫你寫複製提示詞範本，用白話描述打法。

自我檢查

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

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