# 示例 Bot

> 四个从简到繁的示例，每个都能直接跑，每一段逻辑都对应一个 SDK 能力。另有一个完整的参考大脑。

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

示例都在 `brains/examples/`，后一个继承前一个，只加新东西。建议按顺序读：

| 示例 | 学什么 | 跑起来 |
|---|---|---|
| `hello_bot.py` | 采集（一矿 5 人、矿满了去砍树）、造农民（队列只排 1 个）、盖人口建筑、续建停工的地基；四个种族都能跑 | `python tools/play.py --bot brains/examples/hello_bot.py` |
| `rush_bot.py` | 兵营和祭坛（没有就用 `build_near` 盖）、英雄先出（死了复活）、有技能点就学、攒够一波攻击移动 | `… --bot brains/examples/rush_bot.py` |
| `macro_bot.py` | 建造顺序 + 盖完自己回矿（Shift）、人口卡住立刻补、兵营队列 1 个、攻防升级、升本和高级兵、按**地面真实路程**选目标走路径 | `… --bot brains/examples/macro_bot.py --speed 200` |
| `micro_bot.py` | 在运营之上接管战斗：集火最快能打死的、拉残血、英雄保命、夜里挑打得过的野怪点、敌人摸到家门口回防；一拍的命令一批发 | `… --bot brains/examples/micro_bot.py --fair` |

> **说明**
>
> `hello_bot` 和 `rush_bot` 的注释里记了实机踩到的坑，比如「每次都挑第一个工人去盖房子，结果 3 座农场全是半截地基」「写死的兵营坐标正好是树林，3 分钟一座都没盖出来」。读注释比读代码更有收获。

## hello_bot：经济

```python
# 种族 -> (工人, 大厅们, 人口建筑)
RACES = {
    "h": ("hpea", {"htow", "hkee", "hcas"}, "hhou"),
    "o": ("opeo", {"ogre", "ostr", "ofrt"}, "otrb"),
    "u": ("uaco", {"unpl", "unp1", "unp2"}, "uzig"),
    "e": ("ewsp", {"etol", "etoa", "etoe"}, "emow"),
}
MINE_CAP = 5            # 一座矿最多 5 个农民（再多不涨收入）
LUMBER_CREW = 5         # 伐木的人数：每座矿 5 个采金 + 这么多伐木 = 工人目标
```

三件事：闲工人去采金（自己记每座矿几个人，矿满了去砍树）；工人不够就造（队列里只排 1 个）；人口快满就找个没在盖房子的工人在大厅旁边盖人口建筑（人族、兽族还会给停工的地基派人续建）。

## rush_bot：出兵和出击

在 `hello_bot` 上加三件事：兵营和祭坛没有就盖；祭坛出英雄（**死了先复活**，英雄唯一）、有技能点就学；攒到 8 个兵全体攻击移动到敌方大厅，打残了回家重攒。只给闲着的兵下令，避免一拍一拍打断战斗。

## macro_bot：运营基本功

```python
TECH = {
    "h": dict(order=["halt", "hbar", "hbla", "hlum"], altar="halt", hero="Hamg", skills=["AHwe", "AHbz", "AHab"],
              barracks="hbar", soldiers=["hfoo", "hrif", "hkni"], smith="hbla", upgrades=["Rhme", "Rhar", "Rhra", "Rhla"],
              tiers=["hkee", "hcas"]),
    ...
}
```

职业玩家每局都在做的几件事，每一条对应一个 SDK 能力：建造顺序表 + `gather(..., queue="after")` 盖完回矿；`production().blocked` 发现人口卡住；`g.queue` 保证兵营只排 1 个；`can_do` 问引擎能不能研究下一级攻防；升本和高级兵（实机教训：一直停在一本，23 分钟被三本的骑士狮鹫推平）；按 `path_distance` 选目标、用 `path()` 走拐点。

## micro_bot：打起来之后

```python
def _fight(self, g, army, foes, home, now):
    ...
    visible = [e for e in foes if e.visible_to(me)]              # 看不见的目标会被拒（1001）
    atk = [s for s in (g.stats(u) for u in fighters) if s]
    target = min(visible, key=lambda e: _ttk(g, atk, e))         # 最快能打死的，不是最近的
    idle_or_other = [u for u in fighters if g.current_target(u) is None
                     or g.current_target(u).handle != target.handle]
    if idle_or_other:
        g.attack(idle_or_other, target)
```

实机：5 分钟 1497 拍、3023 条命令、0 报错。

## 参考大脑：一个完整的 AI

`brains/xwar3/` 是一个完整的、会开矿打野出击的 AI，分三层：

| 层 | 位置 | 节奏 | 做什么 |
|---|---|---|---|
| 策略层 | `strategy/` | 秒级 | AMAI 式的多战略选择与切换、建造表、反制兵种、选英雄；可选的[大模型运营顾问](https://war3ai.com/docs/llm-coach/) |
| 毫秒层 | `reflex/`（4 个独立进程） | 100 ms 级 | 保命、施法、集火、捡装备 |
| 胜率模型 | `worldmodel/` | — | 打不打得过（推理子集） |

多个进程通过**仲裁表**共享单位，按优先级决定谁说了算：人手 95 > 保命 90 > 躲技能 85 > 施法 80 > 捡装备 70 > … > 策略 50 > 派工 45。你自己的 Bot 在表里的身份是 `bot`，默认优先级 50。

> **注意**
>
> 参考大脑直接用 SDK 的底层（`w3cmd` / `act`），并且大量依赖全图信息。它适合作为「思路」的参考，不建议让大模型直接照抄。它需要 AMAI 数据：`start.bat` 第一次部署时会从 AMAI 的公开仓库拉取并生成（AMAI 为自定义许可，生成物不进 git；没成功的话 `start.bat setup` 重试）。

启动参考大脑最简单的方法是用 [远见指挥台](https://war3ai.com/docs/console/)：在「实例与开局」页勾实例号，点「开始测试」。