fixed # 新增羁绊系统

fixed # 新增遗物系统
fixed # 梦三模式下移除护甲上限限制

mengsan/docs/battle-config.md

@@ -4,7 +4,7 @@
 - 本模块是梦三玩法规则，不批量修改武将技能源码。
 - 主角固定单位 ID：`player`；`ally` 为友方，`enemy` 为敌方。
 - `neutral` 仅保留预设，目前配置为中立会报错，不启用中立行为。
-- 主角使用个人牌堆；友方支援和敌人仍使用公共牌堆。
+- 主角、敌人、羁绊助战使用各自牌堆；其他友方支援使用公共牌堆。
 - 没有 `battlePlan` 的旧关卡继续使用原来随机的一名敌人。
 - 本版单场累计最多 8 个席位，包含主角、初始单位、奖励支援、以后出现的援军。
 
@@ -82,7 +82,8 @@ battlePlan: {
 再将奖励 ID 加入指定 rewardPools。相同奖励来源不叠加人数；临时次数可累加，永久来源保持永久。
 数据保存在 `run.player.supports`，旧存档没有该字段时按空列表处理。
 有限次数只随结算事务提交；重载未完成战斗不会额外扣次，重试结算不会重复发放。
-行囊的“战斗支援”显示来源名称和持续场数。此版本未实现羁绊系统本身。
+行囊的“战斗支援”显示来源名称和持续场数。羁绊助战单独在行军菜单
+“羁绊”中管理，规则和配置见 [bonds.md](bonds.md)。
 
 ## 已接入的示例
 - 林中伏兵“主动追击”：两名初始敌人，第 3 轮必定出现一名敌军援军。

mengsan/docs/bonds.md

@@ -0,0 +1,115 @@
+# 梦三羁绊与助战
+
+## 当前规则
+
+- 行军菜单 → 羁绊：可结识多名 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` 覆盖初始化、事件重复结识、单选、概率边界、
+成长溢出/上限、濒死/救助、独立牌组、结算重复提交和多目标意图。
+另覆盖默认牌库与意图兜底、独立循环、费用不足、自定义意图和击晕期间禁止执行。
+这些检查不等同于游戏原生战斗运行验证；空缺战斗配置待补充后再实机验收。

mengsan/docs/combat-rules.md

@@ -1,10 +1,15 @@
 # 梦三战斗规则（测试阶段）
 
-只影响梦三模式，不修改 noname 的标准/军争原始牌包。`cards/mode-cards.js` 从标准、军争实体牌列表逐一复制模式专属定义，沿用原牌名以保留响应、装备、转化兼容性；图鉴说明在梦三模式覆盖。新征程的界刘备为 50/50 生命，默认每回合摸 2 张、手牌上限 3、回合费用恢复至 3。主动使用牌消耗费用，转化牌按转化后的牌名计费；响应【闪】、救援【桃】等不消耗费用。默认主动牌 1 费，`battle/combat-rules.js` 中列出例外。【杀】1 费、可多次使用，牌定义的基础伤害为 4；【桃】及【桃园结义】回复 8 点生命；【南蛮入侵】、【万箭齐发】、【决斗】、【火攻】基础伤害 4，【闪电】命中伤害 12。其余卡牌保留原有效果，并加上梦三费用与图鉴说明。
+只影响梦三模式，不修改 noname 的标准/军争原始牌包。`cards/mode-cards.js` 从标准、军争实体牌列表逐一复制模式专属定义，沿用原牌名以保留响应、装备、转化兼容性；图鉴说明在梦三模式覆盖。新征程的界刘备为 50/50 生命，默认每回合摸 2 张、手牌上限 3、回合费用恢复至 3。主动使用牌消耗费用，转化牌按转化后的牌名计费；响应【闪】、救援【桃】等不消耗费用。默认主动牌 1 费，`battle/combat-rules.js` 中列出例外。【杀】1 费、可多次使用，牌定义的基础伤害为 6；【桃】及【桃园结义】回复 8 点生命；【南蛮入侵】、【万箭齐发】、【决斗】、【火攻】基础伤害 4，【闪电】命中伤害 12。其余卡牌保留原有效果，并加上梦三费用与图鉴说明。
 
 ## 怪物
 
-`monsters/monster.js` 的 `Monster` 类统一提供阶级默认值。普通／精英／Boss 分别每回合摸 1／2／3 张、手牌上限 3／5／7、回合费用 2／3／4。每名敌人拥有自己的抽牌堆、弃牌堆与手牌；怪物默认使用阶级牌堆，不再从公共牌堆摸牌。友方支援仍用公共牌堆。
+梦三模式护甲不设数值上限，玩家、敌人和友方单位均适用；
+调用 `changeHujia` 时传入的上限参数不生效。
+护甲增减、伤害抵扣与日志仍沿用引擎流程；脆弱仍使获得护甲
+减少 25%（向下取整），劫掠者仍在自身回合开始前清空剩余护甲。
+
+`monsters/monster.js` 的 `Monster` 类统一提供阶级默认值。普通／精英／Boss 分别每回合摸 1／2／3 张、手牌上限 3／5／7、回合费用 2／3／4。每名敌人拥有自己的抽牌堆、弃牌堆与手牌；怪物默认使用阶级牌堆，不再从公共牌堆摸牌。羁绊助战使用各自专属牌堆；其他友方支援仍用公共牌堆。
 
 `HEALTH` 为目前各敌人的独立生命值；新怪物未配置时使用阶级兜底生命值。`OpeningSoldier extends Monster` 是继承示例；新子类在 `MONSTER_TYPES` 注册。关卡单位可以写 `tier`、`hp/maxHp`、`draw`、`handLimit`、`energy`、`deck` 覆盖默认值；`deck` 可为牌名数组（如 `deck:["sha","shan","tao"]`），也可用 `{name,suit,number}` 指定单张牌。牌名必须在 noname 中存在。
 

mengsan/docs/liubei-opening.md

@@ -16,6 +16,7 @@
 - 苏双&张世平为一名男性蜀势力武将，暂设无技能、4/4、4张初始手牌，可自行调整。
 - `discardEquipment` 弃置指定单位装备区的指定牌；已不在装备区则不重复弃置，不影响其他装备。
 - `fixedRewards` 固定获得梅花5的卢一张，加入征程个人牌库；此关关闭随机三选一。奖励与节点完成一起事务提交，重试不会重复发牌。
+- 固定奖励与选择奖励共用过关奖励界面，以“固定战利品”/“可选战利品”等文字区分；固定奖励显示名称和说明，点击“领取固定奖励”后继续结算，不能放弃。若同时配置两类奖励，固定奖励全部获得，候选奖励仍择一领取或放弃。
 - 初始士兵/支援手牌仍来自公共牌堆；弃掉的敌方的卢走原生弃牌流程，胜利所得的卢是持久牌库新卡，并非再从弃牌区拾取。
 - 提前击败敌人允许正常获胜，此时未到第四次回合的支援不会触发。不强行等待、不添加免死。