# War3AI / OpenWar3

> 面向 AI Agent 的《魔兽争霸 III》1.27 开放接口：注入式运行时每 50 ms 推送整张地图的完整状态和事件流；外部程序约一帧下语义命令，每条命令都有回执和原因码。Python SDK（openwar3）用游戏里的叫法（四字码、技能订单名）描述一切。

写 Bot 的最短路径：读「十五条规矩」+ api.json 里的接口，继承 openwar3.Bot，实现 on_start(g) / on_tick(g) / on_event(g, ev)；只使用 api.json 里存在的方法。
全部文档合在一个文件里：https://war3ai.com/llms-full.txt

## 开始

- [文档概览](https://war3ai.com/docs/index.md): OpenWar3 文档：是什么、能做什么；快速开始、写第一个 Bot、让大模型写 AI、接口和协议、网关与 MCP，按你的情况该从哪一页读起。
- [快速开始](https://war3ai.com/docs/quickstart.md): 双击 start.bat 自动装好一切，在远见里设好游戏目录，起一局看示例 Bot 接管。大约 15 分钟。
- [第一个 Bot](https://war3ai.com/docs/first-bot.md): 从 10 行的最小 Bot 开始，加上造农民、盖人口、出兵、英雄和出击，最后读懂回执。

## 让 AI 写 Bot

- [用大模型写一个 Bot](https://war3ai.com/docs/ai-bot.md): 不会编程也能做：你负责说清楚想要它怎么打，大模型负责写代码。复制提示词模板，描述打法，跑起来，再让它改。
- [Agent 自主迭代](https://war3ai.com/docs/agent-loop.md): 让 Coding Agent 自己跑局、读结果、改代码、再跑：它需要一条能无人值守的命令、一份结构化的对局报告和一个明确的目标。
- [大模型当参谋](https://war3ai.com/docs/llm-coach.md): 把「该攒什么、该往哪投人、这一分钟该打还是该缓」交给大模型，规则层只负责执行和否决。参考大脑已经这样做了，这一页讲清楚模式和坑。
- [大模型直接调工具（MCP）](https://war3ai.com/docs/mcp.md): tools/war3_mcp.py 是一个 MCP 服务器。Claude Code、Claude Desktop 或任何支持 MCP 的客户端挂上它，大模型就能直接看局面、下命令、在屏幕上跟玩家说话、弹卡片问玩家、截图看画面，不用先写代码。

## 核心概念

- [心智模型](https://war3ai.com/docs/concepts.md): 快照、命令、回执、事件、一拍、批量。理解这六个概念，就理解了为什么接口长这样，以及怎样写才快。
- [十五条规矩](https://war3ai.com/docs/rules.md): 每一条都是在真实对局里踩出来的。写 Bot 时对照一遍，能省掉大部分排查时间。
- [公平模式](https://war3ai.com/docs/fair-mode.md): 注入进游戏的客户端能读到全图。公平模式让 Bot 只看得见视野里的东西 —— 和人类玩家一样，也和擂台规则一样。

## 指南

- [职业打法食谱](https://war3ai.com/docs/cookbook.md): 高手的优势大多来自几十个「小习惯」。这一页把常见的职业打法逐条落到 SDK 代码上，每段都能直接抄进 on_tick。
- [示例 Bot](https://war3ai.com/docs/examples.md): 四个从简到繁的示例，每个都能直接跑，每一段逻辑都对应一个 SDK 能力。另有一个完整的参考大脑。
- [调试与性能](https://war3ai.com/docs/debugging.md): 一拍为什么慢、命令为什么没生效、游戏为什么不动。按现象排查，再用自带的实机核对脚本确认。

## 玩法扩展

- [RPG 玩伴](https://war3ai.com/docs/companion.md): 在 RPG / 自定义地图里给玩家配一个 AI 伙伴：跟着你、帮你打怪、残血时给你加血、陪你说话。四种形态，继承一个类、改几个属性就是你自己的玩伴。
- [画板](https://war3ai.com/docs/canvas.md): 往游戏画面上画文字框、面板、进度条、图片、贴着地面的圈和带箭头的路线。运行时每帧自己画，不改游戏状态，多人局也安全；Python、HTTP、直接写共享内存都行。
- [界面与输入](https://war3ai.com/docs/ui-input.md): 画板上的按钮、选项卡能点，悬停自动高亮；登记热键、点地面选位置、读鼠标指着哪儿、知道本机玩家选中了谁。点击、热键、放技能、聊天全文、玩家离开，都进事件流。
- [JASS 通道](https://war3ai.com/docs/jass.md): 地图作者能用的 1291 个 JASS 函数，现在可以从游戏外面按名字直接调：造单位、改属性、特效、面板、对话框、声音、镜头、迷雾……远见控制台、命令行、HTTP、Python 四种用法。
- [玩法模组](https://war3ai.com/docs/mods.md): 方案不只是一个替你打的 AI，也可以是一套规则：你自己在游戏窗口里玩，模组负责布置开局、刷怪、给奖励、在屏幕上给你按钮和选项卡、判胜负。继承 openwar3.Mod，一个文件就是一套玩法。

## 工具

- [远见指挥台](https://war3ai.com/docs/console.md): 本机网页控制台，也是唯一的入口：设置游戏目录、起停各项服务、起停游戏实例、设置下一局、看 AI 在想什么、手动下令、导播、对局记录。
- [AI 方案](https://war3ai.com/docs/schemes.md): 一个方案就是一套完整的 AI。在远见里一键切换，正在打的这一局也能立刻换人接管；导出 zip 分享给别人，导入别人的方案来测，每个方案的战绩自动统计。
- [头顶气泡与本地模型](https://war3ai.com/docs/speech.md): 让游戏里任意单位以任意身份头顶弹出对话气泡；接上本地大模型，一句话进、一句回复出在单位头上。
- [网关](https://war3ai.com/docs/gateway.md): WebSocket / JSON 网关：Python SDK 能调的公开接口，JS、C#、Go、Rust、浏览器页面、另一台机器上的程序都能调。三种角色，自带 JS 客户端和浏览器演示页；延迟是快车道再加约 1 ms。

## 参考

- [W3P 协议](https://war3ai.com/docs/protocol.md): 运行时和外部程序之间的全部契约：八块共享内存、读世界状态、读事件、下命令、回执、车道角色、画板、界面与输入。用 Python 以外的语言接入，看这一页。
- [回执与原因码](https://war3ai.com/docs/reason-codes.md): 每条命令的回执都带状态码和原因码。它们是 Bot 和 Agent 自我纠错的依据：把「为什么没做成」变成机器可读的数字。
- [数据从哪来](https://war3ai.com/docs/data-sources.md): 每一类数据的来源和精度。出了「看起来不对」的怪事时，先查这一页。

## 其它

- [常见问题](https://war3ai.com/docs/faq.md): 这是外挂吗？支持哪些版本？AI 能看到什么、能做什么？不会编程能用吗？……
- [使用边界](https://war3ai.com/docs/legal.md): 能做什么、不能做什么，本网站的访问统计，以及商标与第三方许可说明。使用本项目即表示你同意遵守这些边界。

## 接口

- [api.json](https://war3ai.com/api.json): 全部 103 个 Game 方法（name / category / status / latency / mechanism / signature / doc），从代码生成
- [接口目录（网页）](https://war3ai.com/api/): 同一份数据的可搜索版本

## 可选

- [llms-full.txt](https://war3ai.com/llms-full.txt): 全部文档 + 接口目录，一次读完
- [使用边界](https://war3ai.com/docs/legal.md): 只用于自己合法拥有的客户端；不得用于 Battle.net 或任何带反作弊的服务器