# 梦三羁绊与助战

## 当前规则

- 行军菜单 → 羁绊：可结识多名 NPC，但只能指定一名助战；允许不指定。
- 羁绊仅随本次征程保存，新征程重置。刘备先天技能“桃园羁绊”
  初始结识 `guanyu`、`zhangfei`，均为 8 级、升级进度 0%，默认未指定助战。
- 普通事件结识默认 1 级、进度 0%。每级助战概率为 `(level - 1) / 9`，
  1 级为 0%，10 级为 100%。
- 战前在地图切换助战；开战只判定一次。成功后占玩家下家，AI 自动行动。
  原有剧情与道具支援保留，原有 8 席校验和座次代码保留。
- 完成战斗结算：指定 NPC 到场 +50%，未到场 +25%。
  濒死、战斗配置未补齐也属于未到场。不要求 NPC 存活，不限定胜利。
  退出或重载未完成战斗不增长；重复结算不重复增长。
- 100% 进度升一级并保留溢出，最高 10 级，满级不再积累进度。
  升级数值与新增技能从下一场生效。
- 存活 NPC 下一场恢复满血、重建自己的抽牌堆/弃牌堆/消耗牌堆。
  抽牌堆耗尽后洗回自身弃牌堆，无可用牌时不使玩家征程失败。
- NPC 在自身出牌阶段前消耗 1 费用执行当前意图，然后照常使用手牌。
  意图在开场及玩家新一轮行动时预告，按 NPC 自身已执行次数循环。
  NPC 获得的护甲在其下次主循环回合开始时清除，与劫掠者一致。
- 原生死亡结算后离场，存档标记 `down: true`，界面显示“濒死”。
  未救助前不能参战，但仍可指定助战并获得未到场的 25% 进度。
- 怪物意图攻击、负面效果作用于全部存活敌对单位，含剧情与道具友军。
  每个目标承受完整段数，各自结算易伤、护甲与技能；怪物自身增益只执行一次。
  意图伤害数字在目标状态不同时显示伤害范围，护甲仍由伤害流程抵扣。

## 手动补充 NPC

配置位置：`bonds/definitions.js` 的 `bondDefinitions`。

关羽、张飞的 `portrait` 以及 10 个 `growth` 行目前均预留。
成长数值与技能未填写完整前可以结识、选择与成长，但不能参战；
不继承原版武将技能。`deck` 和 `intents` 无需预先填写，已有默认兜底。
`portrait` 为空时不显示原版立绘。

每个成长行的字段：

| 字段 | 含义 |
| --- | --- |
| `maxHp` | 该等级的最大生命，参战时满血，正整数 |
| `hand` | 初始手牌数量，非负整数 |
| `draw` | 自身摸牌阶段摸牌数，非负整数 |
| `handLimit` | 手牌上限，非负整数 |
| `energy` | 每回合费用，正整数 |
| `skills` | 本等级新解锁技能 ID 数组；无新增时填写 `[]`，低等级已解锁技能累计保留 |

`growth[0]` 对应 1 级，`growth[9]` 对应 10 级。数值逐行填写，不自动插值。
当前关卡校验要求生命及初始手牌不超过 99。
`deck` 为该 NPC 独立的基础牌组，填写牌名数组，或 `{name,suit,number}` 数组。
牌名必须已在游戏注册。每场创建新的卡牌实例，不与其他 NPC 或玩家共享实例。

## 默认牌库和意图

`deck` 未填写、为 `null` 或 `[]` 时，使用 `DEFAULT_BOND_DECK`：
3 张【杀】、2 张【闪】、1 张【桃】、1 张【无中生有】，每场独立生成并洗牌。

NPC 的 `intents` 未填写、为 `null` 或 `[]` 时，使用
`bonds/intents.js` 的 `DEFAULT_BOND_INTENTS`，按下列顺序循环：

| 意图 | 效果 |
| --- | --- |
| 援击 | 对每名存活敌对单位造成 6 点攻击伤害 |
| 连击 | 对每名存活敌对单位造成 2 段攻击伤害，每段 3 点 |
| 整备 | 自身获得 5 点护甲 |

默认意图数值不随等级自动插值。NPC 可以在 `bondDefinitions` 中
填写独立的 `intents` 数组来覆盖默认组，例如：

```js
intents: [
    { id: "strike", name: "重击", damage: 8 },
    { id: "break", name: "破阵", damage: 3, hits: 2,
        debuff: "易伤", stacks: 1 },
    { id: "guard", name: "坚守", block: 6 },
],
```

每项需要 `id`、`name`，可配置 `damage`、`hits`、`debuff`、`stacks`、
`block`、`strength`。伤害和增益为非负整数，攻击段数为正整数；
负面效果目前支持“脆弱”“易伤”。`intentType: "death_blow"`
可选，但只允许单段攻击，并沿用出牌阶段结束后自身死亡的规则。
显式填写的无效意图会报错，避免将错误配置静默替换成默认值。

所有攻击目标各自结算护甲、易伤及技能；自身护甲、力量增益只执行一次。
费用不足时该项不产生效果，轮次仍向后推进；每场重新从第一项开始。

## 事件结识接口

剧情选项的 `outcome` 可填写：

```js
outcome: {
    bonds: ["guanyu", { id: "zhangfei", level: 3 }],
}
```

已结识 NPC 再次结识不会重置等级、进度或濒死状态。
也可从 `bonds/state.js` 导入 `meetBond(run, id, level)`，
在现有事件结算中调用并使用现有征程存档流程保存。

## 救助接口预留

`bonds/state.js` 导出 `rescueBond(run, id)`：
仅解除该 NPC 的濒死标记，返回是否发生状态变化。
当前没有绑定道具或取得途径，菜单仅显示禁用的“救助道具待补充”按钮。
以后接入地图道具时，应在同一次存档中完成道具扣除与状态解除；
不能把此接口作为免费救助按钮。救助后下一场按当前等级满血参战。

## 验证

`tools/test_bonds.mjs` 覆盖初始化、事件重复结识、单选、概率边界、
成长溢出/上限、濒死/救助、独立牌组、结算重复提交和多目标意图。
另覆盖默认牌库与意图兜底、独立循环、费用不足、自定义意图和击晕期间禁止执行。
这些检查不等同于游戏原生战斗运行验证；空缺战斗配置待补充后再实机验收。