# 格陣工坊：自動出牌腳本玩家手冊

本指南說明如何撰寫 `deckScript.txt`，讓遊戲依照你的策略出牌、處理 produce 選牌，以及決定起手留牌與換牌。文中的完整範例可以直接複製使用；標示「片段」的範例需放入對應區塊。


> 文件更新：2026-10-29。本文整理此日期專案所支援的玩家腳本語法；實際可用功能以你使用的遊戲版本為準。

你可以用文字描述「先出哪張牌」「放在哪裡」「效果選哪張」「起手留哪些牌」，讓遊戲按照規則自動操作。不需要安裝程式開發工具，也不需要撰寫遊戲底層程式。

第一次使用，請先看第 1、2 節；要修改策略，查第 3 至 11 節；需要一份較完整的起點，直接使用第 16 節。

## 目錄

1. [放置與啟用策略](#section-1)
2. [可直接使用的基本策略](#section-2)
3. [檔案結構與書寫規則](#section-3)
4. [規則先後與多步出牌](#section-4)
5. [條件與比較](#section-5)
6. [定義卡牌集合變數與共用篩選](#section-6)
7. [可使用的資料名稱](#section-7)
8. [查詢操作完整列表](#section-8)
9. [函式與位置語法完整列表](#section-9)
10. [Produce 效果選牌](#section-10)
11. [起手留牌與換牌](#section-11)
12. [保留名稱總表](#section-12)
13. [常見錯誤](#section-13)
14. [查看成功規則](#section-14)
15. [各種語法怎麼搭配](#section-15)
16. [可直接貼上的整合策略](#section-16)
17. [使用限制與分享策略](#section-17)

### 範例如何使用

- **完整策略**：可以整份複製到 `deckScript.txt`，取代舊內容。
- **完整入口範例**：取代檔案中的同名入口，例如整個 `效果選牌 { … }`。不要重複新增同名入口。
- **片段**：放入指定位置，不能單獨當作完整腳本。
- 程式碼框外的說明、Markdown 的三個反引號，以及示意用的 `…` 都不要貼入腳本。
- 範例中的卡牌 ID 是卡牌識別碼，不是中文顯示名稱；指定卡牌的策略只有在符合卡牌及條件時才會命中。

<a id="section-1"></a>

## 1. 放置與啟用策略

1. 在主選單開啟「腳本編輯」，按「產生範例腳本」，或自行將 `.txt` 腳本放入 `gamesettings.json` 所在目錄下的 `playScripts` 資料夾。可存放多個腳本，檔名可以自訂。
2. 以文字編輯器修改腳本，使用 **UTF-8** 儲存。在腳本清單點選要引用的檔案；預設為「無引用」，點選只保存 `SelectedPlayScript` 檔名，不讀取或執行腳本。
3. 新對局開始或重新連線收到狀態同步時，讀取並驗證目前引用的腳本，依「腳本代打」偏好決定是否自動執行。重連會清除舊操作與選牌請求，等待伺服器重新發送請求及回合就緒通知；不重送斷線前的腳本操作。其餘時間修改檔案不會改變當前已載入的策略。
4. 已引用的檔案遺失時，會自動恢復「無引用」並寫回設定檔。選擇「無引用」不會刪除任何檔案。產生範例不會自動引用，也不會覆蓋現有腳本。

舊的設定目錄根層 `deckScript.txt` 不再自動載入；請自行移入 `playScripts` 並從選單引用。

請使用純文字檔，並確認實際檔名不是 `deckScript.txt.txt`。若要停用下一場的自動操作，可關閉「腳本代打」按鈕，或在遊戲關閉時將 `gamesettings.json` 的 `ScriptAutomationEnabled` 設為 `false`。若尚未找到設定目錄或腳本檔，請依遊戲發行頁提供的平台說明定位；不要將腳本貼進 `gamesettings.json`。

空白檔案、只有註解或沒有規則的檔案不會啟用自動操作。語法驗證不通過時，也維持手動操作。

腳本代打預設關閉。對局中的「腳本代打」按鈕可隨時開關代打，並立即將選擇儲存至 `gamesettings.json` 的 `ScriptAutomationEnabled`（預設 `false`）。下一場對局或重新開啟遊戲後，只有設定為 `true` 且腳本合法時才會自動啟用。斷線或對局結束造成的暫停不會改寫此偏好。啟用時顯示亮綠色，停用時顯示暗色，兩種狀態都能點擊；沒有合法可執行腳本時，開啟失敗並顯示「無設定腳本」。規則實際執行成功後，畫面依序顯示「命中規則：名稱」跳字。關閉不會撤回已送出的操作，這些操作仍由伺服器結算。

**沒有適用的一般出牌規則時，遊戲會自動結束回合。不要在腳本中寫「結束回合」。** 如果有選牌或換牌需求，卻沒有適用的對應規則，會交回手動操作。因此建議保留三種入口，並為效果選牌準備最後一條通用規則。

<a id="section-2"></a>

## 2. 可直接使用的基本策略

此策略會優先出能量需求較低且有合法位置的牌；produce 選牌也優先選低能量牌；起手全部保留。

```text
一般操作 {
    規則 "通用出牌" {
        依序 {
            出牌 {
                卡牌 = 手牌 → 篩選(存在(合法落點(目前牌))) → 最低(能量)
                位置 = 合法落點(卡牌) → 取前(1)
            }
        }
    }
}

效果選牌 {
    規則 "通用選牌" {
        選擇 {
            候選牌 → 排序(能量 升序) → 取前(請求.最少選取數)
        }
    }
}

起手換牌 {
    規則 "全部保留" {
        留牌 { 起手牌 }
        其餘 = 換掉
    }
}
```

<a id="section-3"></a>

## 3. 檔案結構與書寫規則

| 名稱 | 用途 |
|---|---|
| `一般操作` | 我方回合的出牌策略 |
| `效果選牌` | produce 等效果要求選牌時的策略 |
| `起手換牌` | 開局留牌、換牌策略 |
| `規則 "名稱"` | 一條具名策略；名稱必須加雙引號 |
| `如果 { … }` | 規則條件，可以省略 |
| `依序 { … }` | 一般操作的出牌步驟，至少一個 |
| `出牌 { … }` | 指定一張卡牌及一個位置 |
| `卡牌 = …`、`位置 = …` | 出牌區塊中的必要欄位，按此順序撰寫 |
| `選擇 { … }` | 效果選牌，內含且僅含一個選牌查詢 |
| `留牌 { … }` | 指定起手要保留的牌 |
| `換牌 { … }` | 指定起手要換掉的牌 |
| `其餘 = 換掉` | 必須搭配留牌模式 |
| `其餘 = 保留` | 必須搭配換牌模式 |

每種入口最多出現一次；同一入口內可以放多條規則，規則名稱不得重複。若要合併兩份策略，請把同類入口的規則合併到同一區塊。

使用半形 `{ } ( ) , . = " "`，查詢連接符號使用 `→`。不使用分號，也不能以 `->` 取代 `→`。縮排方便閱讀，不影響意思。

`//` 後方至該行結尾都是註解。一般文字與規則名稱使用半形雙引號；字串不能跨行。字串內的雙引號寫成 `\"`，反斜線寫成 `\\`。

卡牌 ID 例如 `core_energyRecycle`、`ra_vacuumHerald` 可不加雙引號，也可以寫成 `"core_energyRecycle"`。ID 區分大小寫，應使用卡牌的正確 ID，不是卡牌顯示名稱。

<a id="section-4"></a>

## 4. 規則先後與多步出牌

規則由上往下檢查。條件不符、找不到卡牌或找不到合法位置，就繼續檢查下方規則。

一條一般規則可以包含多個 `出牌`。開始執行該規則時檢查一次 `如果`；後續步驟使用當時最新的手牌、場上單位與數值選擇目標，不再重檢該規則的 `如果`。

每張牌出完並完成動畫與必要選牌後，才執行下一步。整條規則完成後，重新從最上方規則檢查，所以同一規則可以在同回合執行多次。

中途某一步找不到目標時，已出的牌不會撤回；該規則剩餘步驟停止，改查下方規則。換回合後不保留未完成步驟。

**一般出牌的卡牌查詢與位置查詢，各必須選出一個結果。** 沒有結果會略過；多個結果會造成執行錯誤。通常以 `取前(1)`、`最高(…)`、`最低(…)` 或 `隨機取(1)` 收尾。

<a id="section-5"></a>

## 5. 條件與比較

完整範例：

```text
一般操作 {
    規則 "前期部署" {
        如果 {
            我方.HP > 30
            我方.回合數 < 5
            存在(我方單位 → 篩選(id = core_energyRecycle 且 耐久 > 10))
        }
        依序 {
            出牌 {
                卡牌 = 手牌 → 篩選(存在(合法落點(目前牌))) → 最高(能量)
                位置 = 合法落點(卡牌) → 取前(1)
            }
        }
    }
}
```

`如果` 中的每一行都必須成立。省略 `如果` 表示沒有額外條件。

| 寫法 | 意思 |
|---|---|
| `=`、`!=` | 相等、不相等 |
| `>`、`>=`、`<`、`<=` | 大於、大於等於、小於、小於等於；只比較數值 |
| `條件 且 條件` | 兩者皆成立 |
| `條件 或 條件` | 至少一者成立 |
| `非 (條件)` | 條件不成立 |
| `是`、`否` | 布林值，表示成立或不成立 |
| `( … )` | 指定組合順序 |

數值使用整數，支援加法 `+`、減法 `-` 與取負（例如 `-能量`），不支援小數、乘法或除法。加減同優先序，由左至右計算，先於比較與 `且`、`或`；括號可改變順序。兩端必須是數值，不能將文字、布林或集合相加。整數運算超出 32 位元範圍時會報錯。

混用 `且`、`或`、`非` 時建議加括號；`且` 優先於 `或`。否定比較時請寫 `非 (能量 > 3)`，不要寫 `非 能量 > 3`。

<a id="section-6"></a>

## 6. 定義卡牌集合變數與共用篩選

在三種入口區塊外宣告，建議放在檔案最上方：

```text
經濟牌 = core_energyRecycle, core_bank
使者牌 = ra_vacuumHerald
```

變數可以在三種入口的條件與查詢中使用。下列都是查詢片段：

```text
手牌 → 篩選(id = 經濟牌) → 最低(能量)
候選牌 → 篩選(id = 使者牌) → 取前(1)
起手牌 → 篩選(id = 經濟牌)
我方單位 → 篩選(id = 經濟牌) → 最高(耐久)
```

| 寫法 | 意思 |
|---|---|
| `id = 經濟牌` | ID 是集合中任一種 |
| `id != 經濟牌` | ID 不在集合中 |
| `包含(經濟牌, id)` | 與 `id = 經濟牌` 相同 |
| `請求.來源.id = 經濟牌` | 效果選牌的來源屬於經濟牌 |
| `數量(經濟牌)` | 集合中不同 ID 的數量 |

使用限制：

- 變數名稱不加雙引號；`"經濟牌"` 是普通文字，不是變數引用。
- 名稱可用中文字、英文字母、數字與底線，第一字不能是數字；例如 `經濟牌`、`EconomyCards`、`經濟牌2`。
- 不可使用本指南列出的保留名稱，亦不可使用看起來像卡牌 ID 的名稱，例如 `core_group`。
- 每個名稱只能宣告一次；宣告順序不影響引用。
- 至少填一個 ID，多個 ID 用半形逗號分隔；逗號後可以換行，最後一個 ID 後不要加逗號。
- ID 格式為英文字母開頭的英數前綴，加底線，再接英數或底線，例如 `core_bank`。請確認遊戲中確實有該卡牌，拼錯的 ID 不會命中。
- 單一 ID 仍是集合；重複 ID 只計一次。
- 卡牌集合只接受固定 ID，不支援數值變數、變數重新賦值，或用另一個集合變數定義集合；共用篩選則使用下方語法。
- 集合不是實際手牌，不能直接寫 `卡牌 = 經濟牌`；應從 `手牌` 篩選。
- 不支援兩個集合互相比較，例如 `經濟牌 = 使者牌`。

### 共用篩選：宣告一次，多處套用

在入口區塊外寫「名稱 = 篩選(條件)」，後續以「→ 名稱」套用。以下為完整策略：

```text
經濟牌 = core_energyRecycle, core_bank
低費牌 = 篩選(能量 <= 2)
經濟篩選 = 篩選(id = 經濟牌)
可出牌 = 篩選(存在(合法落點(目前牌)))

一般操作 {
    規則 "低費經濟優先" {
        依序 {
            出牌 {
                卡牌 = 手牌 → 經濟篩選 → 低費牌 → 可出牌 → 最低(能量)
                位置 = 合法落點(卡牌) → 取前(1)
            }
        }
    }
}
效果選牌 {
    規則 "優先低費" {
        選擇 { 候選牌 → 低費牌 → 取前(1) }
    }
    規則 "其餘候選" {
        選擇 { 候選牌 → 最低(能量) }
    }
}
起手換牌 {
    規則 "保留低費經濟牌" {
        留牌 { 起手牌 → 經濟篩選 → 低費牌 }
        其餘 = 換掉
    }
}
```

「手牌 → 低費牌」等同「手牌 → 篩選(能量 <= 2)」。連續套用多個名稱表示必須符合所有篩選，後方仍可接排序、取前或其他操作。

也能宣告格子篩選，例如「鄰近敵人 = 篩選(存在(敵方單位 → 範圍內(目前格, 範圍("周圍"))))」，再使用「合法落點(卡牌) → 鄰近敵人 → 取前(1)」。

- 篩選名稱與 ID 集合共用命名規則，不能重名；宣告順序不影響引用，建議集中放在開頭。
- 名稱必須直接接在 → 後方，不加引號或括號；不要寫「篩選(低費牌)」或「低費牌()」。
- 篩選保存條件，不保存結果。每次使用都依當時的牌、單位、格子與玩家數值重新計算。
- 篩選內可以使用 ID 集合，也能在巢狀查詢中引用其他篩選；不可直接或間接循環引用。
- 型別與入口限制在實際引用處檢查。能量篩選可用於卡牌或單位，不能用於格子；包含「合法落點(目前牌)」的篩選只能用於一般操作的卡牌查詢。
- 未使用的宣告只檢查語法、引用結構、循環與展開限制；其型別須在實際引用後才能驗證。
- 目前只宣告單個「篩選(條件)」，不支援把排序、取前或整條查詢存進變數。

<a id="section-7"></a>

## 7. 可使用的資料名稱

### 卡牌與單位來源

| 名稱 | 用途與可用範圍 |
|---|---|
| `手牌` | 我方目前手牌；只用於一般操作 |
| `候選牌` | 本次效果選牌的選項；只用於效果選牌 |
| `起手牌` | 起手換牌時的所有手牌；只用於起手換牌 |
| `可換起手牌` | 起手中允許換掉的牌；只用於起手換牌 |
| `所有單位` | 場上全部單位，包含我方、敵方與中立；三種入口皆可使用 |
| `我方單位` | 場上我方單位；三種入口皆可使用 |
| `敵方單位` | 場上對方單位，不含中立單位；三種入口皆可使用 |
| `中立單位` | 場上不歸屬我方或對方的單位；三種入口皆可使用 |

不能查詢對方隱藏手牌或牌庫內容。

### 玩家數值

以下名稱皆為整數，三種入口均可用：

| 我方 | 對方 | 意思 |
|---|---|---|
| `我方.HP` | `對方.HP` | 玩家 HP |
| `我方.能量` | `對方.能量` | 玩家目前能量 |
| `我方.金幣` | `對方.金幣` | 玩家目前金幣 |
| `我方.回合數` | `對方.回合數` | 該玩家的回合次數 |

注意玩家使用 `對方`，場上單位來源使用 `敵方單位`。

### 卡牌與單位屬性

這些名稱用在卡牌或單位的篩選、排序及評分中，例如 `手牌 → 最低(能量)`。

| 名稱 | 意思 | 資料類別 |
|---|---|---|
| `id` | 卡牌 ID | 文字 |
| `能量` | 卡牌能量需求 | 整數 |
| `價格` | 卡牌價格 | 整數 |
| `耐久` | 卡牌或單位耐久 | 整數 |
| `武力` | 卡牌或單位武力 | 整數 |
| `前線` | 卡牌前線數值 | 整數 |
| `冷卻上限` | 卡牌冷卻上限 | 整數 |
| `冷卻` | 卡牌目前冷卻 | 整數 |
| `種族` | 卡牌的種族標籤 | 文字集合 |
| `狀態` | 卡牌目前的狀態 | 文字集合 |

合法種族名稱：**水族、鳥類、構造物、龍、起源、植物、資源、法術、靈體、武器、工人**。

合法狀態名稱：**停擺、感染、燃燒、冰凍、護盾、新手**。

種族不是陣營。種族及狀態可能同時有多個值，請用 `包含`，不要直接寫 `種族 = "構造物"`。

查詢片段：

```text
手牌 → 篩選(包含(種族, "構造物")) → 最低(能量)
我方單位 → 篩選(包含(狀態, "感染")) → 最高(耐久)
起手牌 → 篩選(數量(狀態) = 0)
手牌 → 篩選(非 包含(狀態, "停擺")) → 取前(1)
```

關鍵詞固定使用上述繁體中文，即使遊戲介面使用其他語言也一樣。`費用`、`攻擊力`、`金錢` 不是合法屬性，請分別使用 `能量`、`武力`、`金幣`。

### 當前選取對象

| 名稱 | 用法 |
|---|---|
| `卡牌` | 這次出牌已選中的牌，只能用在該次 `位置 = …` 查詢 |
| `目前牌` | 卡牌查詢正在檢查的牌 |
| `目前單位` | 單位查詢正在檢查的單位 |
| `目前格` | 位置查詢正在檢查的格子 |

例如 `手牌 → 篩選(存在(合法落點(目前牌)))` 會留下有合法位置的手牌。

巢狀查詢中的「目前」指內層正在檢查的對象。卡牌屬性直接寫 `能量`、`id` 等，不支援 `目前牌.能量` 這類寫法。

### 選牌需求

| 名稱 | 用途 | 可用入口 |
|---|---|---|
| `請求.效果` | 效果種類，目前使用 `produce` | 效果選牌 |
| `請求.來源.id` | 觸發選牌的來源卡牌 ID | 效果選牌 |
| `請求.最少選取數` | 至少要選幾張 | 效果選牌、起手換牌 |
| `請求.最多選取數` | 最多可以選幾張 | 效果選牌、起手換牌 |

<a id="section-8"></a>

## 8. 查詢操作完整列表

查詢由來源開始，以 `→` 接續操作：

`來源 → 操作 → 操作`

下表中的「數值」可以是數字、數值屬性，或 `數量`、`總和` 等得出數值的寫法；「N」是 0 至 4096 的整數或符合該範圍的數值。

| 操作 | 效果 |
|---|---|
| `→ 篩選(條件)` | 保留符合條件的對象 |
| `→ 最高(數值)` | 選出數值最高的一個 |
| `→ 最低(數值)` | 選出數值最低的一個 |
| `→ 排序(數值 升序)` | 從小到大排列，仍保留全部對象 |
| `→ 排序(數值 降序)` | 從大到小排列，仍保留全部對象 |
| `→ 取前(N)` | 選前 N 個；不足 N 個時選全部 |
| `→ 隨機取(N)` | 隨機選最多 N 個，不重複 |
| `→ 範圍內(中心位置, 範圍("名稱"))` | 保留範圍內的單位或格子 |
| `→ 上方(N)` | 把單位或格子轉為其上方 N 格的位置 |
| `→ 下方(N)` | 轉為下方 N 格的位置 |
| `→ 左方(N)` | 轉為左方 N 格的位置 |
| `→ 右方(N)` | 轉為右方 N 格的位置 |

`最高`、`最低` 遇到平手會選來源順序中較前的一個，不會選出多個。排序平手也保留原順序。空集合的最高或最低仍沒有結果。`取前(0)` 與 `隨機取(0)` 都得到空集合；若用於出牌，該步驟會找不到目標；若用於選牌，仍須符合本次最少選取數。

排序建議統一寫成 `排序(能量 升序)`。若使用逗號分隔，方向必須加雙引號，例如 `排序(能量, "升序")`；`排序(能量, 升序)` 不合法。排序只能依數值，不能直接按 `id`、`種族` 或 `狀態` 排序。

方向查詢若讓多個來源指向同一格，只保留該位置一次。`隨機取` 不會重複抽中同一個來源項目，但同名的不同卡牌仍可同時被選中。隨機不是「每次一定換一個結果」。

篩選與排序的先後會改變意思：

- `手牌 → 篩選(存在(合法落點(目前牌))) → 最低(能量)`：在能出的牌中選最低能量。
- `手牌 → 最低(能量) → 篩選(存在(合法落點(目前牌)))`：先選最低能量那張；若不能出就沒有結果，不會改選其他牌。

<a id="section-9"></a>

## 9. 函式與位置語法完整列表

函式直接寫，不接在 `→` 後方；方向函式另有上一節的查詢轉換用法。

| 函式 | 結果與用途 |
|---|---|
| `存在(查詢或文字集合)` | 至少有一個結果或一個文字項目時成立 |
| `數量(查詢或文字集合)` | 結果數量 |
| `總和(查詢, 數值)` | 加總每個對象的指定數值，沒有結果時為 0 |
| `包含(文字集合, 文字)` | 集合是否包含指定文字 |
| `合法落點(卡牌)` | 已選中手牌的合法位置；一般操作的位置查詢使用 |
| `合法落點(目前牌)` | 正在檢查的手牌的合法位置；一般操作的卡牌查詢使用 |
| `可放置(卡牌或目前牌, 位置)` | 指定手牌是否可以放到指定位置；卡牌與目前牌須在各自有效的查詢範圍內 |
| `有單位(位置)` | 該格有任意歸屬的單位 |
| `有我方單位(位置)` | 該格有我方單位 |
| `有敵方單位(位置)` | 該格有對方單位 |
| `上方(位置或目前單位, N)` | 上方 N 格的位置 |
| `下方(位置或目前單位, N)` | 下方 N 格的位置 |
| `左方(位置或目前單位, N)` | 左方 N 格的位置 |
| `右方(位置或目前單位, N)` | 右方 N 格的位置 |
| `範圍("名稱")` | 指定卡牌範圍，例如 `範圍("十字")`、`範圍("周圍")` |

`合法落點` 只適用一般操作，不可拿 produce 候選牌或起手換牌選項查落點。方向位置查詢的距離為 0 至 4096；範圍形狀則固定依下表定義。

### 範圍名稱完整列表

統一寫成 `範圍("名稱")`。範圍與卡牌描述中的同名範圍一致，不可自行修改大小或是否計入中心。以下 33 種範圍都不包含施放中心格；超出棋盤的部分不計入，也不會繞到另一側。

| 名稱 | 涵蓋位置 |
|---|---|
| `橫排` | 中心所在的整條橫排，向左右延伸到棋盤邊緣 |
| `縱排` | 中心所在的整條縱排，向上下延伸到棋盤邊緣 |
| `十字` | 相鄰的上、下、左、右四格 |
| `叉字` | 相鄰的左上、右上、左下、右下四格 |
| `周圍` | 周邊相鄰八格 |
| `全十字` | 上、下、左、右四個方向的整條直線，直到棋盤邊緣 |
| `全叉字` | 四個斜向的整條斜線，直到棋盤邊緣 |
| `全左方` | 同一橫排中，中心左側的所有格子 |
| `全上方` | 同一縱排中，中心上側的所有格子 |
| `全右方` | 同一橫排中，中心右側的所有格子 |
| `全下方` | 同一縱排中，中心下側的所有格子 |
| `上方` | 緊鄰的上方一格 |
| `下方` | 緊鄰的下方一格 |
| `左方` | 緊鄰的左方一格 |
| `右方` | 緊鄰的右方一格 |
| `左上方` | 緊鄰的左上斜角一格 |
| `右上方` | 緊鄰的右上斜角一格 |
| `左下方` | 緊鄰的左下斜角一格 |
| `右下方` | 緊鄰的右下斜角一格 |
| `左右方` | 緊鄰的左方與右方，共兩格 |
| `上下方` | 緊鄰的上方與下方，共兩格 |
| `上方橫排3格` | 左上、正上、右上，共三格 |
| `下方橫排3格` | 左下、正下、右下，共三格 |
| `左方縱排3格` | 左上、正左、左下，共三格 |
| `右方縱排3格` | 右上、正右、右下，共三格 |
| `向上3格` | 正上方連續一、二、三格 |
| `向下3格` | 正下方連續一、二、三格 |
| `向左3格` | 正左方連續一、二、三格 |
| `向右3格` | 正右方連續一、二、三格 |
| `左上轉角` | 正上、左上、正左，共三格 |
| `右上轉角` | 正上、右上、正右，共三格 |
| `左下轉角` | 正下、左下、正左，共三格 |
| `右下轉角` | 正下、右下、正右，共三格 |

範圍名稱必須加雙引號，且使用表中完整名稱。`範圍("上方")` 表示一格範圍；`上方(目前格, 1)` 則取得一個位置，兩者用途不同。

查詢片段，放在出牌的「位置」欄位，可選出周圍敵方數量最多的位置：

```text
位置 = 合法落點(卡牌)
    → 最高(數量(敵方單位 → 範圍內(目前格, 範圍("周圍"))))
```

若要以整條橫排的敵方武力總和評分：

```text
位置 = 合法落點(卡牌)
    → 最高(總和(敵方單位 → 範圍內(目前格, 範圍("橫排")), 武力))
```



方向依棋盤固定方向，不會因輪到另一方而反轉。超出棋盤的位置不能放牌；方向查詢轉換會略過越界結果。位置必須由合法落點或方向查詢取得，目前不能直接寫座標。

### 不分陣營或跨陣營統計

以下為出牌區塊的位置片段。「所有單位」包含我方、敵方與中立，範圍仍不包含中心格。

不分陣營，選十字內武力總和最高的落點：

```text
位置 = 合法落點(卡牌)
    → 最高(總和(所有單位 → 範圍內(目前格, 範圍("十字")), 武力))
```

只計我方與敵方、不計中立，選周圍單位數量合計最多的落點：

```text
位置 = 合法落點(卡牌)
    → 最高(
        數量(我方單位 → 範圍內(目前格, 範圍("周圍")))
        + 數量(敵方單位 → 範圍內(目前格, 範圍("周圍"))))
```

也可用「敵方總和 - 我方總和」評估淨收益；例如把兩邊的數量改為 `總和(查詢, 武力)`，並將 `+` 改為 `-`。

### 十字範圍內，對方武力總和最高的位置

放在 `出牌` 區塊內的「位置」片段：

```text
位置 = 合法落點(卡牌)
    → 最高(總和(
        敵方單位 → 範圍內(目前格, 範圍("十字")),
        武力))
```

### 左右兩邊都有單位的隨機位置

「位置」片段：

```text
位置 = 合法落點(卡牌)
    → 篩選(有單位(左方(目前格, 1)) 且 有單位(右方(目前格, 1)))
    → 隨機取(1)
```

### 我方最高耐久能源回收單位的上方

「位置」片段：

```text
位置 = 我方單位
    → 篩選(id = core_energyRecycle)
    → 最高(耐久)
    → 上方(1)
    → 篩選(可放置(卡牌, 目前格))
```

此寫法先挑最高耐久單位。如果它上方不能放牌，這一步沒有結果，不會自動改找次高耐久單位。

若要在「上方可放牌」的單位中選最高耐久，改用：

```text
位置 = 我方單位
    → 篩選(id = core_energyRecycle)
    → 篩選(可放置(卡牌, 上方(目前單位, 1)))
    → 最高(耐久)
    → 上方(1)
```

### 篩選指定範圍內的特定中立單位

完整一般操作範例。將 `core_bank` 改成要尋找的卡牌 ID：

```text
一般操作 {
    規則 "靠近中立目標" {
        依序 {
            出牌 {
                卡牌 = 手牌 → 篩選(存在(合法落點(目前牌))) → 最低(能量)
                位置 = 合法落點(卡牌)
                    → 篩選(存在(
                        中立單位
                            → 範圍內(目前格, 範圍("周圍"))
                            → 篩選(id = core_bank 且 耐久 > 10)
                    ))
                    → 取前(1)
            }
        }
    }
}
```

此規則只選周圍有指定中立單位、且該單位耐久大於 10 的落點。沒有符合位置時，繼續檢查下方規則；沒有其他可執行規則時自動結束回合。

也可將 `id = core_bank` 改成 `id = 經濟牌`，使用已宣告的卡牌集合變數。`數量(中立單位 → …)` 可計數，`總和(中立單位 → …, 武力)` 可加總武力，用於選擇落點。

「中立」指場上單位不歸屬我方或對方，不是卡牌的中立陣營。原本是中立陣營的卡牌，只要已歸屬玩家，就會列入該玩家的單位。單位歸屬改變後，後續查詢會依新的歸屬判斷。

<a id="section-10"></a>

## 10. Produce 效果選牌

完整入口範例，可取代基本策略的 `效果選牌` 區塊：

```text
效果選牌 {
    規則 "能源回收優先選使者" {
        如果 {
            請求.效果 = produce
            請求.來源.id = core_energyRecycle
        }
        選擇 {
            候選牌 → 篩選(id = ra_vacuumHerald) → 取前(1)
        }
    }
    規則 "其餘選最高能量" {
        選擇 {
            候選牌 → 最高(能量)
        }
    }
}
```

目前 produce 需要選一張牌。第一條找不到使者時，繼續檢查第二條。選出數量不符合本次需求，也會繼續檢查下方規則。

一個 `選擇` 區塊只能放一個查詢；不能把第一選擇與第二選擇分成兩行塞在同一區塊，應拆成兩條規則。

效果選牌優先於接下來的出牌步驟。自動選牌完成後，才繼續原本的出牌策略。如果沒有任何適用規則而交回手動，腳本會暫停；完成手動選牌不代表一定會自動恢復腳本。

<a id="section-11"></a>

## 11. 起手留牌與換牌

### 留牌模式

完整入口範例：

```text
起手換牌 {
    規則 "保留組合與低能量牌" {
        留牌 {
            起手牌 → 篩選(id = core_energyRecycle) → 取前(1)
            起手牌 → 篩選(能量 <= 2) → 最低(能量)
        }
        其餘 = 換掉
    }
}
```

先保留一張能源回收，再從尚未選中的起手牌保留一張低能量牌。

### 換牌模式

完整入口範例，與上面的留牌模式擇一使用：

```text
起手換牌 {
    規則 "換掉高能量牌" {
        換牌 {
            可換起手牌 → 篩選(能量 >= 5)
        }
        其餘 = 保留
    }
}
```

每條規則只能選擇留牌或換牌一種模式。區塊中可以有多行查詢，逐行累積選取；已選中的那張牌不會再次被後面的查詢選中。同名的兩張卡牌仍是兩張不同的牌。

找不到符合的換牌對象，可以合法地一張也不換。留牌模式若沒有留下任何牌，表示換掉全部可換的起手牌。不可換的牌始終保留。

每次起手換牌只處理一次，不會再次更換新抽到的牌。

<a id="section-12"></a>

## 12. 保留名稱總表

下列名稱依各節說明使用，不可用來命名變數；並非每個名稱都能單獨構成一句指令。

| 類別 | 名稱 |
|---|---|
| 入口 | 一般操作、效果選牌、起手換牌 |
| 規則結構 | 規則、如果、依序、出牌、卡牌、位置、選擇、留牌、換牌、其餘、換掉、保留 |
| 資料來源 | 手牌、起手牌、可換起手牌、候選牌、我方單位、敵方單位、中立單位、所有單位 |
| 當前對象 | 目前牌、目前格、目前單位 |
| 屬性 | id、能量、價格、耐久、武力、前線、冷卻上限、冷卻、種族、狀態 |
| 資料前綴與名稱 | 我方、對方、請求、HP、produce |
| 邏輯與值 | 是、否、非、且、或 |
| 查詢操作 | 篩選、最高、最低、排序、取前、隨機取、範圍內 |
| 查詢參數 | 升序、降序 |
| 函式 | 包含、存在、數量、總和、合法落點、可放置、有單位、有我方單位、有敵方單位 |
| 方向與範圍 | 上方、下方、左方、右方、範圍 |
| 禁止作為指令或變數 | 結束回合 |

`回合數`、`金幣`、`效果`、`來源.id`、`最少選取數`、`最多選取數` 的完整可用名稱請依第 7 節；不要省略所需的 `我方.`、`對方.` 或 `請求.`。

<a id="section-13"></a>

## 13. 常見錯誤

| 問題寫法或狀況 | 正確做法 |
|---|---|
| `id == core_bank` | 使用單一等號：`id = core_bank` |
| `卡牌 = 手牌`，手牌有多張 | 加上 `取前(1)`、`最高`、`最低` 或 `隨機取(1)` |
| `位置 = 合法落點(卡牌)`，有多個位置 | 加上 `→ 取前(1)` 等明確選取方式 |
| `排序(種族 升序)` | 排序依據必須是數值，例如 `排序(能量 升序)` |
| `篩選(種族 = "構造物")` | 使用 `篩選(包含(種族, "構造物"))` |
| `篩選(id = "經濟牌")` | 引用集合變數時不加引號：`篩選(id = 經濟牌)` |
| `卡牌 = 經濟牌` | 使用 `卡牌 = 手牌 → 篩選(id = 經濟牌) → 取前(1)` |
| 使用 `目前牌.能量` | 在卡牌查詢內直接寫 `能量` |
| 用卡牌顯示名稱代替 ID | 使用正確卡牌 ID |
| 沒有合適的牌就停在那裡 | 一般操作會自動結束回合；如想繼續出其他牌，請在下方加通用規則 |
| 只寫一般操作，沒有選牌或換牌規則 | 遇到無適用策略的互動會交回手動；建議補齊三種入口 |
| 在規則中寫 `結束回合` | 刪除該動作；沒有可執行的一般規則時會自動結束回合 |

腳本最長 65536 個字元，查詢巢狀最多 64 層。過於龐大的策略或重複組合也可能超過大小或計算限制，請拆簡條件與查詢。未支援的功能包括迴圈、自訂函式、字串拼接與執行中變數賦值。

<a id="section-14"></a>

## 14. 查看成功規則

設定目錄中的 `ScriptLog.txt` 只列出命中並成功完成的規則，例如：

```text
[event1]命中 規則全部保留
[event2]命中 規則通用出牌
```

多步出牌規則須全部步驟成功完成才有該規則的成功紀錄。沒有命中的規則、只完成部分步驟的規則，以及自動結束回合，都不列入這份紀錄。每場啟用合法策略的新對局會重新開始記錄。

<a id="section-15"></a>

## 15. 各種語法怎麼搭配

### 15.1 先認識查詢與單一結果

`手牌`、`我方單位`、`合法落點(卡牌)` 都是一組對象。`篩選` 會縮小集合，`排序` 只改變順序，`最高`、`最低` 才會從非空集合選出一個結果。

| 目的 | 查詢片段 |
|---|---|
| 選一張最低能量手牌 | `手牌 → 最低(能量)` |
| 選兩張最低能量候選牌 | `候選牌 → 排序(能量 升序) → 取前(2)` |
| 保留所有能量不超過 2 的起手牌 | `起手牌 → 篩選(能量 <= 2)` |
| 找所有感染中的敵方單位 | `敵方單位 → 篩選(包含(狀態, "感染"))` |
| 找最多敵方單位相鄰的合法落點 | `合法落點(卡牌) → 最高(數量(敵方單位 → 範圍內(目前格, 範圍("周圍"))))` |

第二列只是選多張的語法示意；目前 produce 只接受一張，不能直接用它回覆 produce。

### 15.2 條件是判斷，不是指令

以下為 `如果` 區塊片段，可放在規則名稱後、`依序`／`選擇`／`留牌`／`換牌` 前面：

```text
如果 {
    我方.HP <= 30
    我方.能量 >= 2
    數量(敵方單位) >= 2
    非 存在(我方單位 → 篩選(包含(狀態, "感染")))
}
```

上面的四個條件必須全部成立。`如果` 只能放條件，不能在裡面出牌、宣告變數，或再放另一個 `如果`。也沒有 `否則` 語法；要安排第二選擇，寫下一條規則。

運算結合順序由高到低為：括號內的內容、`非`／數值取負、比較、`且`、`或`、`→`。不要把數值比較串成 `1 < 能量 < 5`；應寫 `能量 > 1 且 能量 < 5`。

### 15.3 一條規則連出兩張牌

完整入口範例，可取代原本的 `一般操作`：

```text
一般操作 {
    規則 "先出最低能量再出最高武力" {
        如果 {
            數量(手牌) >= 2
        }
        依序 {
            出牌 {
                卡牌 = 手牌 → 篩選(存在(合法落點(目前牌))) → 最低(能量)
                位置 = 合法落點(卡牌) → 取前(1)
            }
            出牌 {
                卡牌 = 手牌 → 篩選(存在(合法落點(目前牌))) → 最高(武力)
                位置 = 合法落點(卡牌) → 取前(1)
            }
        }
    }
    規則 "剩餘手牌" {
        依序 {
            出牌 {
                卡牌 = 手牌 → 篩選(存在(合法落點(目前牌))) → 最低(能量)
                位置 = 合法落點(卡牌) → 取前(1)
            }
        }
    }
}
```

第二步會重新查看第一張牌結算後的手牌和合法位置；不會預先鎖定兩張牌，也不保證第二張一定能出。第二步失敗時，第一張不會撤回，接著檢查「剩餘手牌」。

每個 `出牌` 的 `卡牌` 只代表該步剛選中的牌，不能用它引用前一步的卡牌或落點。

### 15.4 對卡牌、玩家與格子使用正確屬性

- `能量`：查詢當中的卡牌或單位屬性。
- `我方.能量`：玩家目前的能量。
- `目前格`：正在評估的位置，可交給範圍或方向函式。

例如這是一般操作的卡牌查詢片段：

```text
手牌 → 篩選(能量 <= 我方.能量 且 存在(合法落點(目前牌))) → 最高(武力)
```

只比較能量不足以判斷能否出牌；還有位置、目標等限制，所以保留 `存在(合法落點(目前牌))`。

格子沒有 `能量` 或 `武力` 屬性。若要評分落點，必須透過周圍單位的數量、總和等數值，例如第 9 節的範圍範例。

### 15.5 查詢中再放查詢

以下是「位置」片段：

```text
位置 = 合法落點(卡牌)
    → 最高(總和(
        敵方單位 → 範圍內(目前格, 範圍("十字")),
        武力))
```

它會對每個合法落點，找出該位置十字範圍內的敵方單位，再加總那些單位的武力，最後選出總和最高的位置。

這裡的 `目前格` 是外層正在評分的格子；`總和` 的 `武力` 是逐一計算的敵方單位屬性。進入內層 `篩選` 或評分時，「目前」對象會換成內層項目；不要在單位篩選條件裡把 `目前格` 當成可以任意引用的外層變數。

### 15.6 明確選擇零張

以下是完整起手換牌入口，表示全部保留：

```text
起手換牌 {
    規則 "不換任何牌" {
        換牌 {
            可換起手牌 → 取前(0)
        }
        其餘 = 保留
    }
}
```

`留牌 { }` 與 `換牌 { }` 也接受空區塊：前者表示不主動留任何可換牌，後者表示不換任何牌。為了方便閱讀與分享，建議使用明確查詢。`選擇 { }` 則不合法，效果選牌必須寫一個查詢。

<a id="section-16"></a>

## 16. 可直接貼上的整合策略

**以下是完整策略，可以整份取代 `deckScript.txt`。** 它示範集合變數、優先規則、範圍評分、效果選牌和起手留牌；用於學習語法，不代表最適合每一副牌組。

```text
// 依自己的牌組修改這組卡牌 ID。
經濟牌 = core_energyRecycle, core_bank

一般操作 {
    規則 "前期優先經濟牌" {
        如果 {
            我方.回合數 <= 3
        }
        依序 {
            出牌 {
                卡牌 = 手牌
                    → 篩選(id = 經濟牌)
                    → 篩選(存在(合法落點(目前牌)))
                    → 最低(能量)
                位置 = 合法落點(卡牌) → 取前(1)
            }
        }
    }
    規則 "其餘優先低能量並靠近敵方" {
        依序 {
            出牌 {
                卡牌 = 手牌
                    → 篩選(存在(合法落點(目前牌)))
                    → 最低(能量)
                位置 = 合法落點(卡牌)
                    → 最高(數量(敵方單位 → 範圍內(目前格, 範圍("周圍"))))
            }
        }
    }
}

效果選牌 {
    規則 "優先經濟牌" {
        選擇 {
            候選牌 → 篩選(id = 經濟牌) → 取前(請求.最少選取數)
        }
    }
    規則 "其餘選低能量" {
        選擇 {
            候選牌 → 排序(能量 升序) → 取前(請求.最少選取數)
        }
    }
}

起手換牌 {
    規則 "留一張經濟牌與其他低能量牌" {
        留牌 {
            起手牌 → 篩選(id = 經濟牌) → 最低(能量)
            起手牌 → 篩選(能量 <= 2)
        }
        其餘 = 換掉
    }
}
```

這份策略會有以下行為：

1. 起手優先保留一張最低能量的經濟牌，再保留其餘能量不超過 2 的牌。
2. 我方回合數不超過 3 時，優先出有合法落點的經濟牌。
3. 其他情況選有合法落點的最低能量手牌，放到周圍敵方單位最多的位置。若所有位置分數相同，取來源順序較前的位置。
4. 效果選牌先找經濟牌；數量不足時，改用低能量候選牌。
5. 每次規則完成後重新從第一條檢查；沒有可執行的一般規則時自動結束回合。

想調整落點偏好，可以把 `敵方單位` 換成 `我方單位`，或將 `最高` 換成 `最低`。這只會改變位置評分，不會改變卡牌本身的效果範圍。

<a id="section-17"></a>

## 17. 使用限制與分享策略

### 支援範圍

- 只使用本文列出的關鍵詞與函式；介面語言改變不會改變腳本關鍵詞。
- 沒有迴圈、自訂函式、`否則`、字串拼接、任意座標、檔案引用或執行中的變數賦值。
- 不能查詢對方隱藏手牌、牌庫內容或任意遊戲內部資料。
- 不能預先模擬一串出牌的結果。多步規則是逐步實際出牌，失敗不會回復之前的動作。
- 所有出牌仍須符合遊戲合法操作；腳本不能透過選定位置略過出牌限制。
- 回放與觀戰不執行自動出牌。斷線重連後，本局需改用手動操作，新對局再載入策略。

### 大小與計算限制

| 項目 | 限制 |
|---|---|
| 腳本文字長度 | 最多 65536 個字元 |
| 語法單元數 | 最多 16384 個；大量名稱、符號與條件可能先達到此限制 |
| 運算式深度 | 最多 64 層；過長的連續查詢鏈也可能達到限制 |
| 篩選展開語法節點 | 最多 65536 個；包含宣告檢查與各引用處的展開，深度亦受 64 層限制 |
| 卡牌集合引用展開總量 | 最多 65536 個項目；同一大集合在許多地方引用也會累計 |
| `取前`、`隨機取` 與方向距離 | 求值後必須是 0 至 4096 的整數 |
| 單次決策計算量 | 由遊戲限制；過於複雜的查詢可能超限並停止腳本 |

數值過大或加總超出可表示範圍也可能產生錯誤。遇到限制時，簡化條件、縮短查詢、減少重複的大集合引用。

### 分享前確認

- 附上適用的遊戲版本、牌組和策略目的。
- 提供完整腳本，或明確標註應替換哪個入口。
- 將卡牌 ID 與用途一併說明；卡牌名稱不能直接代替 ID。
- 同類入口合併在一起，並確保同一入口中的規則名稱不重複。
- 保留通用的效果選牌規則，避免沒有符合條件的候選牌時交回手動。
- 先在遊戲中確認語法與實際行為，再分享；可參照 `ScriptLog.txt` 確認哪些規則成功完成。