# War3AI / OpenWar3

> 為 AI Agent 打造的《魔獸爭霸 III》1.27 開放介面：注入式執行環境每 50 ms 推送整張地圖的完整狀態與事件流；外部程式約一幀即可下達語意命令，每條命令都有回執和原因碼。Python SDK（openwar3）用遊戲裡的叫法（四字碼、技能指令名）描述一切。

寫 Bot 的最短路徑：讀「十五條規矩」+ api.json 裡的 API，繼承 openwar3.Bot，實作 on_start(g) / on_tick(g) / on_event(g, ev)；只使用 api.json 裡存在的方法。
所有文件合併在一個檔案中：https://war3ai.com/zh-tw/llms-full.txt

## 開始

- [文件總覽](https://war3ai.com/zh-tw/docs/index.md): OpenWar3 文件：是什麼、能做什麼；快速開始、寫第一個 Bot、讓 LLM 寫 AI、API 和協定、閘道與 MCP，依你的情況該從哪一頁讀起。
- [快速開始](https://war3ai.com/zh-tw/docs/quickstart.md): 按兩下 start.bat 自動裝好一切，在遠見裡設定好遊戲目錄，開一局看範例 Bot 接管。大約 15 分鐘。
- [第一個 Bot](https://war3ai.com/zh-tw/docs/first-bot.md): 從 10 行的最小 Bot 開始，加上生產農民、蓋農場補人口、出兵、英雄和出擊，最後看懂回執。

## 讓 AI 寫 Bot

- [用 LLM 寫一個 Bot](https://war3ai.com/zh-tw/docs/ai-bot.md): 不會寫程式也能做：你負責說清楚想要它怎麼打，LLM 負責寫程式碼。複製提示詞範本，描述打法，跑起來，再讓它修改。
- [Agent 自主迭代](https://war3ai.com/zh-tw/docs/agent-loop.md): 讓 Coding Agent 自己跑對局、讀結果、改程式碼、再跑：它需要一條能無人值守執行的命令、一份結構化的對局報告，以及一個明確的目標。
- [LLM 當參謀](https://war3ai.com/zh-tw/docs/llm-coach.md): 把「該存什麼、該往哪裡派人、這一分鐘該打還是該緩」交給 LLM，規則層只負責執行和否決。參考大腦已經這樣做了，這一頁把模式和陷阱講清楚。
- [LLM 直接呼叫工具（MCP）](https://war3ai.com/zh-tw/docs/mcp.md): tools/war3_mcp.py 是一個 MCP 伺服器。Claude Code、Claude Desktop 或任何支援 MCP 的用戶端掛上它，LLM 就能直接看局面、下命令、在螢幕上跟玩家說話、跳出卡片詢問玩家、截圖看畫面，不必先寫程式碼。

## 核心概念

- [心智模型](https://war3ai.com/zh-tw/docs/concepts.md): 快照、命令、回執、事件、一拍、批次。理解這六個概念，就理解了 API 為什麼長這樣，以及怎麼寫才快。
- [十五條規矩](https://war3ai.com/zh-tw/docs/rules.md): 每一條都是在真實對局裡踩坑踩出來的。寫 Bot 時對照一遍，能省下大部分除錯時間。
- [公平模式](https://war3ai.com/zh-tw/docs/fair-mode.md): 注入遊戲的用戶端能讀到全圖。公平模式讓 Bot 只看得見視野內的東西 —— 和人類玩家一樣，也和擂台規則一致。

## 指南

- [職業打法食譜](https://war3ai.com/zh-tw/docs/cookbook.md): 高手的優勢大多來自幾十個「小習慣」。這一頁把常見的職業打法逐條落實到 SDK 程式碼上，每段都能直接貼進 on_tick。
- [範例 Bot](https://war3ai.com/zh-tw/docs/examples.md): 四個由淺入深的範例，每個都能直接執行，每一段邏輯都對應一項 SDK 能力。另附一個完整的參考大腦。
- [偵錯與效能](https://war3ai.com/zh-tw/docs/debugging.md): 一拍為什麼慢、命令為什麼沒生效、遊戲為什麼不動。依現象排查，再用內建的實機核對腳本確認。

## 玩法擴展

- [RPG 玩伴](https://war3ai.com/zh-tw/docs/companion.md): 在 RPG / 自訂地圖裡幫玩家配一個 AI 夥伴：跟著你、幫你打怪、殘血時幫你補血、陪你聊天。四種形態，繼承一個類別、改幾個屬性，就是你自己的玩伴。
- [畫板](https://war3ai.com/zh-tw/docs/canvas.md): 在遊戲畫面上畫文字框、面板、進度條、圖片、貼著地面的圈和帶箭頭的路線。執行環境每幀自己繪製，不修改遊戲狀態，多人局也安全；Python、HTTP、直接寫共享記憶體都行。
- [介面與輸入](https://war3ai.com/zh-tw/docs/ui-input.md): 畫板上的按鈕、選項卡片能點，滑鼠停在上面會自動醒目顯示；登記熱鍵、點地面選位置、讀取滑鼠指著哪裡、知道本機玩家選取了誰。點擊、熱鍵、放技能、聊天全文、玩家離開，都會進入事件流。
- [JASS 通道](https://war3ai.com/zh-tw/docs/jass.md): 地圖作者能用的 1291 個 JASS 函式，現在可以從遊戲外面依名稱直接呼叫：造單位、改屬性、特效、面板、對話框、聲音、鏡頭、迷霧……遠見指揮台、命令列、HTTP、Python 四種用法。
- [玩法模組](https://war3ai.com/zh-tw/docs/mods.md): 方案不只是一個替你打的 AI，也可以是一套規則：你自己在遊戲視窗裡玩，模組負責布置開局、刷怪、給獎勵、在螢幕上提供按鈕和選項卡片、判定勝負。繼承 openwar3.Mod，一個檔案就是一套玩法。

## 工具

- [遠見指揮台](https://war3ai.com/zh-tw/docs/console.md): 本機網頁控制台，也是唯一的入口：設定遊戲目錄、啟動／停止各項服務、啟動／停止遊戲實例、設定下一局、查看 AI 在想什麼、手動下令、導播、對局紀錄。
- [AI 方案](https://war3ai.com/zh-tw/docs/schemes.md): 一個方案就是一套完整的 AI。在遠見裡一鍵切換，正在打的這一局也能立刻換人接管；匯出 zip 分享給別人，匯入別人的方案來測試，每個方案的戰績自動統計。
- [頭頂氣泡與本機模型](https://war3ai.com/zh-tw/docs/speech.md): 讓遊戲裡任意單位以任意身分在頭頂彈出對話氣泡；接上本機 LLM，一句話輸入，一句回覆就出現在單位頭上。
- [閘道](https://war3ai.com/zh-tw/docs/gateway.md): WebSocket / JSON 閘道：Python SDK 能呼叫的公開 API，JS、C#、Go、Rust、瀏覽器頁面、另一台電腦上的程式都能呼叫。三種角色，附 JS 用戶端和瀏覽器示範頁；延遲是快車道再加約 1 ms。

## 參考

- [W3P 協定](https://war3ai.com/zh-tw/docs/protocol.md): 執行環境和外部程式之間的全部契約：八塊共享記憶體、讀取世界狀態、讀取事件、下命令、回執、車道角色、畫板、介面與輸入。要用 Python 以外的語言接入，請看這一頁。
- [回執與原因碼](https://war3ai.com/zh-tw/docs/reason-codes.md): 每條命令的回執都帶有狀態碼和原因碼。它們是 Bot 和 Agent 自我修正的依據：把「為什麼沒做成」變成機器可讀的數字。
- [資料從哪裡來](https://war3ai.com/zh-tw/docs/data-sources.md): 每一類資料的來源與精度。遇到「看起來不對」的怪事時，先查這一頁。

## 其他

- [常見問題](https://war3ai.com/zh-tw/docs/faq.md): 這是外掛嗎？支援哪些版本？AI 能看到什麼、能做什麼？不會寫程式能用嗎？……
- [使用邊界](https://war3ai.com/zh-tw/docs/legal.md): 能做什麼、不能做什麼，本網站的流量統計，以及商標與第三方授權說明。使用本專案即表示你同意遵守這些邊界。

## API

- [api.json](https://war3ai.com/zh-tw/api.json): 全部 103 個 Game 方法（name / category / status / latency / mechanism / signature / doc），由程式碼產生
- [API 目錄（網頁）](https://war3ai.com/zh-tw/api/): 同一份資料的可搜尋版本

## 選用

- [llms-full.txt](https://war3ai.com/zh-tw/llms-full.txt): 所有文件 + API 目錄，一次讀完
- [使用邊界](https://war3ai.com/zh-tw/docs/legal.md): 僅適用於自己合法擁有的用戶端；不得用於 Battle.net 或任何有反作弊機制的伺服器