文档概览

OpenWar3 是 War3AI 的开放接口层：一个注入进《魔兽争霸 III》1.27 的运行时，加一套 Python SDK。

• 运行时每 50 ms 把整张地图的完整状态推进共享内存：全部玩家的资源和人口，所有单位的血蓝、订单、正在打谁、技能冷却、buff、背包，地上物品，树，生产队列，昼夜。还有一条事件流：单位出现和死亡、每一下伤害、生产完成……
• 外部程序以约一帧的延迟下语义命令：移动、攻击、采集、建造、训练、施法、学技能、复活、用物品、买东西……每条命令都有回执，写明引擎接没接、没接的原因码。
• 你只需要说「做什么」：单位用四字码、技能用订单名，和游戏里的叫法一致；「怎么做到」由运行时负责。

因此大模型不需要任何底层知识，也不需要看画面。读完文档，它就能写出一个会运营、会打架的 Bot，上场之后再根据回执和事件自己修改。

不只是对战：画板 能往游戏画面上画自己的面板和标注，界面与输入 让画出来的按钮能点、热键能响，JASS 通道 能从外面调用游戏里的 1291 个函数，在 RPG 地图里还能给自己配一个 AI 玩伴。写好的 AI 可以做成 方案，一键切换、导出分享；一整套新玩法可以写成 玩法模组。

不写 Python 也能接：网关 让任何语言、浏览器页面用 WebSocket / JSON 调同样的接口，MCP 服务器 让 Claude Code 这类 Agent 直接调工具看局面、下命令。

按你的情况选一条路

你是	从这里读	然后
会玩魔兽，不会编程	快速开始 → 用大模型写一个 Bot	遇到问题看 常见问题
会 Python	第一个 Bot → 心智模型 → 十五条规矩	职业打法食谱、示例 Bot
在做 Coding Agent / 自动化	Agent 自主迭代	回执与原因码、llms-full.txt
想让大模型在局内做决策	大模型当参谋	头顶气泡与本地模型
想让 Agent 直接上手操作（Claude Code 等）	大模型直接调工具（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/         头顶聊天气泡 + 本地大模型
runtime/        多实例编排（每局按设置重开）
data/           order-ids.txt；从你自己的游戏提取数据的工具
schemes/        你的 AI 方案（mine/）和别人分享的方案（installed/），不进仓库
tools/          play.py（一条命令起局）、run_scheme.py（方案运行器）、war3_mcp.py（MCP 服务器）、run_tests.py、实机核对脚本
docs/           接口目录 api.json（从代码生成）、协议、手册

运行时和你的代码之间只隔着一份带版本的 W3P 协议：用 Python SDK 最省事，用别的语言照着协议接入也可以。

接口的「实测状态」是什么意思

接口目录里每个接口都标了三种状态之一：

• 实机验证过：底层那条路（动作号、参数形状、读回的效果）在真实对局里验证过，有核对脚本守着。
• 实验：新加的接口，已经在演练实例上跑通，还在逐项实机验证。可以用，接口细节可能还会调整。
• 推断 / 未完整实测：底层机制照抄引擎自己的做法（比如 JASS 的等价函数），但还没在对局里逐项核对。用之前先看回执。