整合

mengsan/docs/battle-config.md

@@ -0,0 +1,98 @@
+# 梦三：关卡条件与战斗支援
+
+## 约定
+- 本模块是梦三玩法规则，不批量修改武将技能源码。
+- 主角固定单位 ID：`player`；`ally` 为友方，`enemy` 为敌方。
+- `neutral` 仅保留预设，目前配置为中立会报错，不启用中立行为。
+- 主角使用个人牌堆；友方支援和敌人仍使用公共牌堆。
+- 没有 `battlePlan` 的旧关卡继续使用原来随机的一名敌人。
+- 本版单场累计最多 8 个席位，包含主角、初始单位、奖励支援、以后出现的援军。
+
+## 配置位置
+节点内容或剧情选项的 `outcome.battle` 中增加 `battlePlan`。
+Boss 也可以在大关配置的 `bossBattlePlan` 中定义。
+`units` 中每一项是一名初始角色，因此数组长度就是初始非主角人数。
+
+```js
+battlePlan: {
+  units: [
+    { id: "captain", character: "re_xiahoudun", camp: "enemy", hand: 4 },
+    { id: "guard", character: "re_xuzhu", camp: "enemy", hand: 2 },
+  ],
+  rules: [
+    {
+      id: "rescue", name: "友军驰援",
+      when: { event: "roundStart", round: 3 },
+      effects: [{ type: "spawn", unit: {
+        id: "helper", character: "re_zhangliao", camp: "ally", hand: 4,
+      } }],
+    },
+    {
+      id: "low_hp", name: "背水一战",
+      when: { event: "state", all: [
+        { unit: "captain", field: "alive", value: true },
+        { unit: "captain", field: "hp", op: "lte", value: 2 },
+      ] },
+      effects: [{ type: "draw", target: "captain", amount: 2 }],
+    },
+    {
+      id: "supply", name: "主角补给",
+      when: { event: "state", all: [
+        { unit: "player", field: "hand", op: "lte", value: 1 },
+      ] },
+      effects: [{ type: "draw", target: "player", amount: 2 }],
+    },
+  ],
+}
+```
+
+## 字段
+初始/援军单位：`id`、`character`、`camp`；可选 `hand`（默认 4）、`hp`、`maxHp`、`skills`。
+每个单位 ID 必须唯一，引用 ID 而不是武将名称，允许同武将的不同单位。
+
+每条规则每场仅触发一次，效果按书写顺序执行；不支持任意脚本、eval 或无限重复规则。
+- `when.event`：`battleStart` 开场、`roundStart` 新轮、`turnStart` 每名角色主循环回合开始、`state` 状态变化。
+- `when.round`：至少到第 N 轮。主角第一次进入主循环为第 1 轮；额外技能回合不另计轮。
+- `when.turn`：至少到主循环第 N 个回合；所有角色一起计数，额外技能回合不计。
+- `when.actor`：限定当前主循环行动单位，可用于 turnStart/roundStart。
+- `when.all`：所有条件同时满足。`hp`、`hand` 使用 `eq`/`gte`/`lte` 比较。
+- `alive`、`linked`、`turnedOver` 比较布尔值；`camp` 比较 `ally`/`enemy`。
+- state 在开场、回合边界及体力/手牌/死亡/横置/翻面事件后检查，不轮询。
+
+效果：`spawn`（提供 unit）、`draw`/`recover`/`maxHp`（target + amount）、`skill`（target + skill）、`camp`（target + camp）。
+主角不能改阵营；死亡或尚未出现的目标不会执行数值/技能增益。规则不会复活角色。
+`skill` 为本场增加技能，战后随角色统一释放，不写入永久技能。
+
+`blocksVictory: true` 用于必须等待的敌方援军波次；未触发时不会提前胜利。
+默认 false，避免可选援军条件永久不成立导致战斗无法结束。
+若设为 true，作者必须保证该条件可以达成。条件同样适用于玩家方。
+
+## 奖励支援
+在奖励注册表中配置 support，不设置旧的 effectId：
+```js
+"shared.reward.support.example": {
+  name: "道具·援令", description: "本次征程后续每场战斗获得友方支援。",
+  support: {
+    category: "item", // item 道具、bond 羁绊来源（仅数据预留）、buff 其他增益
+    battles: -1,      // -1 或省略：本征程持续；正整数 N：持续 N 场战斗
+    unit: { character: "re_zhangliao", camp: "ally", hand: 4 },
+  },
+},
+```
+再将奖励 ID 加入指定 rewardPools。相同奖励来源不叠加人数；临时次数可累加，永久来源保持永久。
+数据保存在 `run.player.supports`，旧存档没有该字段时按空列表处理。
+有限次数只随结算事务提交；重载未完成战斗不会额外扣次，重试结算不会重复发放。
+行囊的“战斗支援”显示来源名称和持续场数。此版本未实现羁绊系统本身。
+
+## 已接入的示例
+- 林中伏兵“主动追击”：两名初始敌人，第 3 轮必定出现一名敌军援军。
+- 敌军队长体力不高于 2 时摸两张；主角手牌不多于 1 时补两张，各限一次。
+- 斥候谢礼奖励池加入“道具·斥候援令”，本征程后续每场由友方张辽参战。
+
+## 结算和清理
+仅主角死亡判负；存活友军不阻碍胜利。清空敌军且没有必须等待的敌军规则后判胜。
+援军使用原生加入座次/enterGame，登记玩家 ID、技能释放和战斗资源清理。
+身份模式原有的杀反贼摸三张、误杀忠臣弃牌惩罚不沿用；奖励由梦三结算和上述规则决定。
+统计记录实际战败敌军数量，而非固定每场加一。
+
+已做隔离配置/规则/事务检查；未启动游戏、未进行实际战斗或界面验收。

mengsan/docs/combat-rules.md

@@ -0,0 +1,20 @@
+# 梦三战斗规则（测试阶段）
+
+只影响梦三模式，不修改 noname 的标准/军争原始牌包。`content/mode-cards.js` 从标准、军争实体牌列表逐一复制模式专属定义，沿用原牌名以保留响应、装备、转化兼容性；图鉴说明在梦三模式覆盖。新征程的界刘备为 50/50 生命，默认每回合摸 2 张、手牌上限 3、回合费用恢复至 3。主动使用牌消耗费用，转化牌按转化后的牌名计费；响应【闪】、救援【桃】等不消耗费用。默认主动牌 1 费，`runtime/combat-rules.js` 中列出例外。【杀】1 费、可多次使用，牌定义的基础伤害为 4；【桃】及【桃园结义】回复 8 点生命；【南蛮入侵】、【万箭齐发】、【决斗】、【火攻】基础伤害 4，【闪电】命中伤害 12。其余卡牌保留原有效果，并加上梦三费用与图鉴说明。
+
+## 怪物
+
+`runtime/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 中存在。
+
+## 配置位置
+
+- 玩家费用、手牌上限、卡牌费用与【杀】伤害：`runtime/combat-rules.js`
+- 梦三模式卡牌复制、内容与图鉴文案：`content/mode-cards.js`
+- 怪物阶级、默认牌堆、生命与继承示例：`runtime/monster.js`
+- 刘备角色初始生命：`content/scenario-characters.js`
+- 刘备专属初始牌组：`content/card-library.js`
+- 首关小兵覆盖数值：`content/acts/act1/stories/liubei-opening.js`
+
+旧存档不作迁移。源码检查不等于游戏内、十周年 UI 或 AI 行为验收。

mengsan/docs/liubei-opening.md

@@ -0,0 +1,26 @@
+# 刘备首关配置
+
+新征程仅显示梦三私有界刘备：4/4、无初始技能。原版界刘备和其他模式不变；旧征程不强行换主角。
+
+## 编辑入口
+`content/acts/act1/stories/liubei-opening.js`：
+- `openingDialogue`：开战前播放。原先填写的穿越与关张对话误放在第四回合支援台词里，现已移到这里。
+- `openingDialogue` 中的 `type:"choice"` 可让玩家选择刘备发言；`flag` 指定征程存档的 `storyFlags` 键，选中后存入选项 `id`。后续台词可用 `when:{flag:"...",equals:"选项id"}` 控制是否显示。选项会随本关胜利结算写入征程存档，后续关卡可据此分支；中途退出战斗不会单独保存选择。
+- 每段对话左上角可点“跳过对话”。尚未选择的发言会采用该行的 `defaultChoice`；未配置时采用 `choices` 第一项，并照常写入 `storyFlags`。已手动选择的发言不会被跳过操作覆盖。一个选项的发言也有效。
+- `reinforcementDialogue`：刘备第四次完整回合结束时的台词，空数组跳过。
+- `victoryDialogue`：胜利后、奖励结算前台词；失败不播放，不给马。
+- `battlePlan.units`：敌人；`skills` 添加技能，`inheritSkills:false` 不加载原武将技能。
+- `hand` 初始手牌数（可为0）、`hp` 当前体力、`maxHp` 上限；`equipment` 初始装备，指定 name/suit/number，可选nature。同一普通装备槽不可重复。
+- `when:{event:"turnEnd",actor:"player",actorTurns:4}`：主角本人第四次回合结束，不是全场第四回合，也不是第四轮开始。额外完整回合也计数。
+- 支援单位 `after:"player"` 插入刘备下家；该支援仅当前战斗有效，不写入永久道具/羁绊。
+- 苏双&张世平为一名男性蜀势力武将，暂设无技能、4/4、4张初始手牌，可自行调整。
+- `discardEquipment` 弃置指定单位装备区的指定牌；已不在装备区则不重复弃置，不影响其他装备。
+- `fixedRewards` 固定获得梅花5的卢一张，加入征程个人牌库；此关关闭随机三选一。奖励与节点完成一起事务提交，重试不会重复发牌。
+- 初始士兵/支援手牌仍来自公共牌堆；弃掉的敌方的卢走原生弃牌流程，胜利所得的卢是持久牌库新卡，并非再从弃牌区拾取。
+- 提前击败敌人允许正常获胜，此时未到第四次回合的支援不会触发。不强行等待、不添加免死。
+
+## 新角色立绘
+`assets/sushuang-zhangshiping.png` 为本次 image_gen 生成的原创双人立绘，不是官方素材。
+
+## 验证边界
+隔离脚本检查配置、回合计数、效果顺序及奖励幂等，不等于游戏/十周年UI验收。请开始新征程检查真实引擎的装备、座次、AI和剧情显示。