# 文件總覽

> OpenWar3 文件：是什麼、能做什麼；快速開始、寫第一個 Bot、讓 LLM 寫 AI、API 和協定、閘道與 MCP，依你的情況該從哪一頁讀起。

來源: https://war3ai.com/zh-tw/docs/

**OpenWar3** 是 War3AI 的開放介面層：一個注入《魔獸爭霸 III》1.27 的執行環境，加上一套 Python SDK。

- 執行環境每 **50 ms** 把整張地圖的完整狀態推送到共用記憶體：所有玩家的資源與人口，所有單位的血量魔力、指令、正在攻擊誰、技能冷卻、buff、物品欄，地上的物品、樹木、生產佇列、晝夜。另外還有一條**事件流**：單位出現與死亡、每一下傷害、生產完成……
- 外部程式以**約一幀**的延遲下達**語意命令**：移動、攻擊、採集、建造、訓練、施法、學技能、復活、使用物品、購買物品……每條命令都有**回執**，寫明引擎有沒有接下，沒接下時附上原因碼。
- 你只需要說「做什麼」：單位用四字碼、技能用指令名，和遊戲裡的叫法一致；「怎麼做到」交給執行環境。

因此 LLM 不需要任何底層知識，也不需要看畫面。讀完文件，它就能寫出一個會運營、會打仗的 Bot，上場之後再依據回執和事件自行修正。

不只是對戰：[畫板](https://war3ai.com/zh-tw/docs/canvas/)能在遊戲畫面上畫出自己的面板和標註，[介面與輸入](https://war3ai.com/zh-tw/docs/ui-input/)讓畫出來的按鈕能點、熱鍵按了有反應，[JASS 通道](https://war3ai.com/zh-tw/docs/jass/)能從外部呼叫遊戲裡的 1291 個函式，在 RPG 地圖裡還能幫自己配一個[AI 玩伴](https://war3ai.com/zh-tw/docs/companion/)。寫好的 AI 可以做成[方案](https://war3ai.com/zh-tw/docs/schemes/)，一鍵切換、匯出分享；一整套新玩法可以寫成[玩法模組](https://war3ai.com/zh-tw/docs/mods/)。

不寫 Python 也能接入：[閘道](https://war3ai.com/zh-tw/docs/gateway/)讓任何語言、瀏覽器頁面透過 WebSocket / JSON 呼叫同樣的 API，[MCP 伺服器](https://war3ai.com/zh-tw/docs/mcp/)讓 Claude Code 這類 Agent 直接呼叫工具看局面、下命令。

  - [快速開始](https://war3ai.com/zh-tw/docs/quickstart/): 裝好環境，一條命令開一局，看範例 Bot 接手。
  - [用 LLM 寫一個 Bot](https://war3ai.com/zh-tw/docs/ai-bot/): 不會寫程式也沒關係：複製提示詞、描述打法，交給 Agent。
  - [心智模型](https://war3ai.com/zh-tw/docs/concepts/): 快照、命令、回執、事件、一拍。寫 Bot 前花五分鐘讀一遍。
  - [API 目錄](https://war3ai.com/zh-tw/api/): 所有 API，每一個都標註了實測狀態、延遲等級和底層機制。

## 依你的情況選一條路

| 你是 | 從這裡讀 | 接著 |
|---|---|---|
| 會玩魔獸，不會寫程式 | [快速開始](https://war3ai.com/zh-tw/docs/quickstart/) → [用 LLM 寫一個 Bot](https://war3ai.com/zh-tw/docs/ai-bot/) | 遇到問題看 [常見問題](https://war3ai.com/zh-tw/docs/faq/) |
| 會 Python | [第一個 Bot](https://war3ai.com/zh-tw/docs/first-bot/) → [心智模型](https://war3ai.com/zh-tw/docs/concepts/) → [十五條規矩](https://war3ai.com/zh-tw/docs/rules/) | [職業打法食譜](https://war3ai.com/zh-tw/docs/cookbook/)、[範例 Bot](https://war3ai.com/zh-tw/docs/examples/) |
| 在做 Coding Agent／自動化 | [Agent 自主迭代](https://war3ai.com/zh-tw/docs/agent-loop/) | [回執與原因碼](https://war3ai.com/zh-tw/docs/reason-codes/)、[`llms-full.txt`](https://war3ai.com/zh-tw/llms-full.txt) |
| 想讓 LLM 在局內做決策 | [LLM 當參謀](https://war3ai.com/zh-tw/docs/llm-coach/) | [頭頂氣泡與本機模型](https://war3ai.com/zh-tw/docs/speech/) |
| 想讓 Agent 直接上手操作（Claude Code 等） | [LLM 直接呼叫工具（MCP）](https://war3ai.com/zh-tw/docs/mcp/) | [介面與輸入](https://war3ai.com/zh-tw/docs/ui-input/) |
| 使用其他語言（JS、C#、Go、Rust……） | [閘道](https://war3ai.com/zh-tw/docs/gateway/) | 更底層：[W3P 協定](https://war3ai.com/zh-tw/docs/protocol/) |
| 想讓不同人的 AI 互相對戰 | [公平模式](https://war3ai.com/zh-tw/docs/fair-mode/) | [對戰平台](https://war3ai.com/zh-tw/arena/) |
| 想在 RPG／自訂地圖裡打造自己的玩法 | [玩法模組](https://war3ai.com/zh-tw/docs/mods/) | [介面與輸入](https://war3ai.com/zh-tw/docs/ui-input/)、[畫板](https://war3ai.com/zh-tw/docs/canvas/)、[JASS 通道](https://war3ai.com/zh-tw/docs/jass/)、[RPG 玩伴](https://war3ai.com/zh-tw/docs/companion/) |
| 想把自己的 AI 分享給別人 | [AI 方案](https://war3ai.com/zh-tw/docs/schemes/) | [遠見指揮台](https://war3ai.com/zh-tw/docs/console/) |

## 儲存庫裡有什麼

```text
start.bat       唯一的入口：從零部署 + 開啟遠見；stop.bat 徹底停止全部
sdk/python/     介面層。openwar3/ 是對外門面（Game + Bot），從這裡開始
brains/         決策層
  examples/       hello_bot（經濟）→ rush_bot（出兵）→ macro_bot（運營）→ micro_bot（微操 + 練功）；buddy（RPG 玩伴）；
                  mod_hero_roguelike / mod_endless_defense（玩法模組）
  xwar3/          參考大腦：策略層（秒級）+ 毫秒層（4 個行程）+ 勝率模型
console/        遠見網頁指揮台（FastAPI + React）
gateway/        閘道（WebSocket / JSON）+ JS 用戶端 + 瀏覽器示範頁
director/       自動運鏡、頭頂血條
speech/         頭頂聊天氣泡 + 本機 LLM
runtime/        多實例編排（每局依設定重開）
data/           order-ids.txt；從你自己的遊戲擷取資料的工具
schemes/        你的 AI 方案（mine/）和別人分享的方案（installed/），不納入儲存庫
tools/          play.py（一條命令開局）、run_scheme.py（方案執行器）、war3_mcp.py（MCP 伺服器）、run_tests.py、實機核對腳本
docs/           API 目錄 api.json（由程式碼產生）、協定、手冊
```

執行環境和你的程式碼之間只隔著一份帶版本號的 [W3P 協定](https://war3ai.com/zh-tw/docs/protocol/)：用 Python SDK 最省事，用其他語言照著協定接入也可以。

## API 的「實測狀態」是什麼意思

API 目錄裡的每個 API 都標註了以下三種狀態之一：

- **實機驗證**：底層那條路徑（動作編號、參數形式、讀回的效果）已在真實對局中驗證，並有核對腳本把關。
- **實驗**：新加入的 API，已在測試實例上跑通，還在逐項實機驗證。可以使用，API 細節可能還會調整。
- **推斷／未完整實測**：底層機制照搬引擎自己的做法（例如 JASS 的等價函式），但還沒在對局裡逐項核對。使用前先看回執。

> **說明**
>
> 目前只支援**《魔獸爭霸 III》1.27**（寒冰霸權）。1.24 ~ 1.28 是同一套引擎結構，多版本相容列在[路線圖](https://war3ai.com/zh-tw/roadmap/)的 P4 階段；1.29 之後及重製版是另一套引擎，不在承諾範圍內。