# 文档概览

> OpenWar3 文档：是什么、能做什么；快速开始、写第一个 Bot、让大模型写 AI、接口和协议、网关与 MCP，按你的情况该从哪一页读起。

来源: https://war3ai.com/docs/

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

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

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

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

不写 Python 也能接：[网关](https://war3ai.com/docs/gateway/) 让任何语言、浏览器页面用 WebSocket / JSON 调同样的接口，[MCP 服务器](https://war3ai.com/docs/mcp/) 让 Claude Code 这类 Agent 直接调工具看局面、下命令。

  - [快速开始](https://war3ai.com/docs/quickstart/): 装好环境，一条命令起一局，看示例 Bot 接管。
  - [用大模型写一个 Bot](https://war3ai.com/docs/ai-bot/): 不会编程也行：复制提示词，描述打法，交给 Agent。
  - [心智模型](https://war3ai.com/docs/concepts/): 快照、命令、回执、事件、一拍。写 Bot 前花五分钟读一遍。
  - [接口目录](https://war3ai.com/api/): 全部接口，每个都标了实测状态、延迟档位和底层机制。

## 按你的情况选一条路

| 你是 | 从这里读 | 然后 |
|---|---|---|
| 会玩魔兽，不会编程 | [快速开始](https://war3ai.com/docs/quickstart/) → [用大模型写一个 Bot](https://war3ai.com/docs/ai-bot/) | 遇到问题看 [常见问题](https://war3ai.com/docs/faq/) |
| 会 Python | [第一个 Bot](https://war3ai.com/docs/first-bot/) → [心智模型](https://war3ai.com/docs/concepts/) → [十五条规矩](https://war3ai.com/docs/rules/) | [职业打法食谱](https://war3ai.com/docs/cookbook/)、[示例 Bot](https://war3ai.com/docs/examples/) |
| 在做 Coding Agent / 自动化 | [Agent 自主迭代](https://war3ai.com/docs/agent-loop/) | [回执与原因码](https://war3ai.com/docs/reason-codes/)、[`llms-full.txt`](https://war3ai.com/llms-full.txt) |
| 想让大模型在局内做决策 | [大模型当参谋](https://war3ai.com/docs/llm-coach/) | [头顶气泡与本地模型](https://war3ai.com/docs/speech/) |
| 想让 Agent 直接上手操作（Claude Code 等） | [大模型直接调工具（MCP）](https://war3ai.com/docs/mcp/) | [界面与输入](https://war3ai.com/docs/ui-input/) |
| 用别的语言（JS、C#、Go、Rust……） | [网关](https://war3ai.com/docs/gateway/) | 更底层：[W3P 协议](https://war3ai.com/docs/protocol/) |
| 想让不同人的 AI 对打 | [公平模式](https://war3ai.com/docs/fair-mode/) | [对战平台](https://war3ai.com/arena/) |
| 想在 RPG / 自定义地图里造自己的玩法 | [玩法模组](https://war3ai.com/docs/mods/) | [界面与输入](https://war3ai.com/docs/ui-input/)、[画板](https://war3ai.com/docs/canvas/)、[JASS 通道](https://war3ai.com/docs/jass/)、[RPG 玩伴](https://war3ai.com/docs/companion/) |
| 想把自己的 AI 分享给别人 | [AI 方案](https://war3ai.com/docs/schemes/) | [远见指挥台](https://war3ai.com/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/         头顶聊天气泡 + 本地大模型
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 协议](https://war3ai.com/docs/protocol/)：用 Python SDK 最省事，用别的语言照着协议接入也可以。

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

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

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

> **说明**
>
> 目前只支持**魔兽争霸 III 1.27**（冰封王座）。1.24 ~ 1.28 是同一套引擎结构，多版本适配在 [路线图](https://war3ai.com/roadmap/) 的 P4 阶段；1.29 之后和重制版是另一套引擎，不在承诺范围内。