# 範例 Bot

> 四個由淺入深的範例，每個都能直接執行，每一段邏輯都對應一項 SDK 能力。另附一個完整的參考大腦。

來源: https://war3ai.com/zh-tw/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` 詢問引擎能不能研究下一級攻防；升級主堡和高階兵種（實機教訓：一直停在 T1，23 分鐘被 T3 的騎士、獅鷲騎士推平）；依 `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 式的多戰略選擇與切換、建造表、反制兵種、選英雄；可選的 [LLM 運營顧問](https://war3ai.com/zh-tw/docs/llm-coach/) |
| 毫秒層 | `reflex/`（4 個獨立行程） | 100 ms 級 | 保命、施法、集火、撿裝備 |
| 勝率模型 | `worldmodel/` | — | 打不打得贏（推理子集） |

多個行程透過**仲裁表**共用單位，依優先順序決定誰說了算：手動操作 95 > 保命 90 > 閃避技能 85 > 施法 80 > 撿裝備 70 > … > 策略 50 > 派工 45。你自己的 Bot 在表裡的身分是 `bot`，預設優先順序為 50。

> **注意**
>
> 參考大腦直接使用 SDK 的底層（`w3cmd`／`act`），而且大量依賴全圖資訊。它適合當作「思路」參考，不建議讓 LLM 直接照抄。它需要 AMAI 資料：`start.bat` 第一次部署時會從 AMAI 的公開儲存庫拉取並產生（AMAI 採自訂授權，產出的檔案不納入 git；沒有成功的話，用 `start.bat setup` 重試）。

啟動參考大腦最簡單的方法是用[遠見指揮台](https://war3ai.com/zh-tw/docs/console/)：在「實例與開局」頁勾選實例編號，點「開始測試」。