文件總覽

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

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

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

不只是對戰：畫板能在遊戲畫面上畫出自己的面板和標註，介面與輸入讓畫出來的按鈕能點、熱鍵按了有反應，JASS 通道能從外部呼叫遊戲裡的 1291 個函式，在 RPG 地圖裡還能幫自己配一個AI 玩伴。寫好的 AI 可以做成方案，一鍵切換、匯出分享；一整套新玩法可以寫成玩法模組。

不寫 Python 也能接入：閘道讓任何語言、瀏覽器頁面透過 WebSocket / JSON 呼叫同樣的 API，MCP 伺服器讓 Claude Code 這類 Agent 直接呼叫工具看局面、下命令。

依你的情況選一條路

你是	從這裡讀	接著
會玩魔獸，不會寫程式	快速開始 → 用 LLM 寫一個 Bot	遇到問題看 常見問題
會 Python	第一個 Bot → 心智模型 → 十五條規矩	職業打法食譜、範例 Bot
在做 Coding Agent／自動化	Agent 自主迭代	回執與原因碼、llms-full.txt
想讓 LLM 在局內做決策	LLM 當參謀	頭頂氣泡與本機模型
想讓 Agent 直接上手操作（Claude Code 等）	LLM 直接呼叫工具（MCP）	介面與輸入
使用其他語言（JS、C#、Go、Rust……）	閘道	更底層：W3P 協定
想讓不同人的 AI 互相對戰	公平模式	對戰平台
想在 RPG／自訂地圖裡打造自己的玩法	玩法模組	介面與輸入、畫板、JASS 通道、RPG 玩伴
想把自己的 AI 分享給別人	AI 方案	遠見指揮台

儲存庫裡有什麼

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 協定：用 Python SDK 最省事，用其他語言照著協定接入也可以。

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

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

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