diff --git a/design/gdd/systems/战斗循环/敌人系统.md b/design/gdd/systems/战斗循环/敌人系统.md index 55dd744c..6ef15fe2 100644 --- a/design/gdd/systems/战斗循环/敌人系统.md +++ b/design/gdd/systems/战斗循环/敌人系统.md @@ -1,7 +1,7 @@ # 敌人系统 > 一句话：敌人数据、技能池出招、意图呈现 -> 状态：已定稿；现行为 v2.1 +> 状态：已定稿；现行为 v2.2 ## 设计目的 @@ -179,9 +179,9 @@ Boss 专属身份 = 专属池承载：独占技能 + 权重轮廓（**技能错 | 冷却 | 照常——条件与冷却各自独立排除，同一拍可叠加 | | 保底 | 保底特殊技集合同样排除条件不满足的技能（保底禁止逼出条件不满足的技）；池构成纪律"每池至少一行无条件特殊技"保证该集合闸外恒非空——间隔闸期内可被闸排空，保底顺延（见「三道闸」表） | | 死亡作废 | 照常——摇定后兑现前死亡，本拍作废、不进冷却不进保底计数 | -| 意图呈现 | 三档规格不变——情境技属特殊技，走类型级预告＋结算明细具名，因果由技能名承载（如"趁隙偷袭"）；闩型保留解锁弹出规格（见"目标顺位与意图线索"节） | +| 意图呈现 | 三档规格不变——情境技属特殊技，走类型级预告＋结算明细具名，因果由技能名承载（如"趁隙偷袭"）；闩型解锁拍零新增呈现，告知归既有意图预告承载（见"目标顺位与意图线索"节） | -半血解锁：Boss 解锁技＝trigger {fact: self_hp_pct, op: lte, value: 行值, latch: 真}——解锁弹出规格（归因明细行＋一次性技能名 toast）、单向闩语义、双面过滤。 +半血解锁：Boss 解锁技＝trigger {fact: self_hp_pct, op: lte, value: 行值, latch: 真}——解锁拍零新增呈现（归因明细行照记数据面）、单向闩语义、双面过滤。 首批落地（已实装）：①三 Boss 解锁技为闩型条件；②两个示范投放——地精池＋低血防御增益「孤注守势」（self_hp_pct lte 35，纯增益）、L2/L3 群行位＋停手偷袭伤害技「趁隙偷袭」（last_round_end eq 停手）。投放敌种、权重与阈值投值归[难度曲线与Boss](../冒险循环/难度曲线与Boss.md)；"每池增益≤1"纪律不动，条件技照常计入预算。 @@ -205,7 +205,7 @@ Boss 专属身份 = 专属池承载：独占技能 + 权重轮廓（**技能错 即：普攻完全不可预测；特殊技有一次类型级预告，不可撤销，但给"继续挖还是停手"的决策依据。攻击系内部不分档预告——重击与普通伤害技的预告呈现完全相同，强度差异的感知通道是敌人本体的准备动画（规格见[角色设计](../../../art/character-design.md) §5.6 意图准备动画三档）。 -**半血解锁弹出规格（解锁判定点=通用事件「血量阈值 `enemy_hp_threshold`」的发射点，对所有带闩型血量触发条件的敌人逐个发射、非 Boss 专属——Boss 语义留给订阅条件判定；条件载体=技能行 trigger 闩型，见「触发条件」节）**：Boss 血量降至解锁阈值（trigger 行值，域 [1,99]，缺省无字段=无门槛）时，下一个开轮摇号前出一次归因明细行「XX 解锁了 YY」（高光键为技能解锁，行型复用高光行零新增）；呈现层对该行弹**一次性技能名 toast**（轻量提示，非演出——零动画资产、不改演出规格），只报技能名不报数值，池与权重不公开纪律不变。解锁=单向闩（治疗抬血不解锁）；锁定条目双面过滤（不进可摇集合与保底特殊技集合——保底禁止逼出未解锁技）；解锁后冷却初值 0 即可摇。投放纪律=机制通用、闩型解锁用例仅 Boss 专属技投放（enemy 表无 boss 编码位，硬闸须跨表查节点类型——不做硬闸，本句即文档纪律登记）。技能动画的攻/防系映射归[战斗表现](战斗表现.md)，敌人侧摇定动画位归[HUD 框架](../表现与支撑/HUD框架.md)（呈现载体 = 站桩立绘，2026-09-20 全站桩拍板），本系统只锁上面这张三档规格。 +**半血解锁呈现规格（解锁判定点=通用事件「血量阈值 `enemy_hp_threshold`」的发射点，对所有带闩型血量触发条件的敌人逐个发射、非 Boss 专属——Boss 语义留给订阅条件判定；条件载体=技能行 trigger 闩型，见「触发条件」节）**：Boss 血量降至解锁阈值（trigger 行值，域 [1,99]，缺省无字段=无门槛）时，下一个开轮摇号前出一次归因明细行「XX 解锁了 YY」（高光键为技能解锁，行型复用高光行零新增——数据面照记，玩家不可见面）。**解锁拍零新增呈现（2026-11-10 用户裁，替代原一次性技能名 toast）**：血条跌破本身即视觉事件，新增提示条、弹窗、浮字一概不做——玩家刚把 Boss 打进阈值，「它亮新招」因果自明；新技的玩家告知由既有意图预告承载（下一拍开轮摇中即类型级徽标顶头，具名随预告），与杀戮尖塔敌人能力变化走头顶意图的惯例同轨。池与权重不公开纪律不变。解锁=单向闩（治疗抬血不解锁）；锁定条目双面过滤（不进可摇集合与保底特殊技集合——保底禁止逼出未解锁技）；解锁后冷却初值 0 即可摇。投放纪律=机制通用、闩型解锁用例仅 Boss 专属技投放（enemy 表无 boss 编码位，硬闸须跨表查节点类型——不做硬闸，本句即文档纪律登记）。技能动画的攻/防系映射归[战斗表现](战斗表现.md)，敌人侧摇定动画位归[HUD 框架](../表现与支撑/HUD框架.md)（呈现载体 = 站桩立绘，2026-09-20 全站桩拍板），本系统只锁上面这张三档规格。 | 规格 | 含义 | |---|---| diff --git a/design/gdd/systems/表现与支撑/HUD框架.md b/design/gdd/systems/表现与支撑/HUD框架.md index 0c0fd803..a165a389 100644 --- a/design/gdd/systems/表现与支撑/HUD框架.md +++ b/design/gdd/systems/表现与支撑/HUD框架.md @@ -57,7 +57,7 @@ HUD框架站在玩家与全部玩法系统之间：挖掘期它是输入的翻 | 区 | 位置与几何 | 管什么 | |---|---|---| -| B 战斗画面 | 全宽，高读布局表 `stage_h`（背景三关变体＋连续地面层高另读 `ground_h`） | 三关舞台背景＋连续地面层、主角站桩立绘、敌人站桩立绘 ×1–3（**全站桩形态，2026-09-20 用户拍板：无框立绘+底座、状态小图标挂血条下，英雄卡/敌人卡退役**）、轮次阶段指示、结算明细带 | +| B 战斗画面 | 全宽，高读布局表 `stage_h`（背景三关变体＋连续地面层高另读 `ground_h`） | 三关舞台背景＋连续地面层、主角站桩立绘、敌人站桩立绘 ×1–3（**全站桩形态，2026-09-20 用户拍板：无框立绘+底座、状态小图标挂血条下，英雄卡/敌人卡退役**）、轮次阶段指示（结算明细带已退役，2026-11-10 用户裁——B 区零文字带，规格见 [battle.md](../../../ux/battle.md)「即时反馈画面化预览」节） | | C 角色信息 | 左下，宽读 `info_panel_w`，高 = 基准屏高 − B 区高 | 生命 / 攻击 / 储备数据框、状态效果槽、小人立绘 | | D 扫雷图 | 中下，宽 = 基准屏宽 − C 区宽 − 列间距，高同 C 区（2026-11-07 顶栏搬两侧：D 区全高归棋盘） | 左/右行动资源侧栏、棋盘本体、toast 槽（棋盘底常驻操作提示条退役） | @@ -80,7 +80,7 @@ HUD框架站在玩家与全部玩法系统之间：挖掘期它是输入的翻 ### 提示与弹层：轻提示随起随消、重弹层排队进出 -界面弹出的东西分两族。toast（从棋盘区上缘内侧浮出的轻提示条）是非模态的：弹出期间玩家照常操作棋盘，约 2.5 秒自动消退、不劫持输入。模态覆盖层（弹出期间挡住下方操作、要先处理才能继续的那种弹层）则相反，图例面板、结算明细回看、胜负终局画面都属于这族。 +界面弹出的东西分两族。toast（从棋盘区上缘内侧浮出的轻提示条）是非模态的：弹出期间玩家照常操作棋盘，约 2.5 秒自动消退、不劫持输入。模态覆盖层（弹出期间挡住下方操作、要先处理才能继续的那种弹层）则相反，图例面板、胜负终局画面都属于这族（结算明细回看覆盖层已随明细带退役报废，2026-11-10 用户裁）。 | 弹出物 | 模态性 | 进出规则 | |---|---|---| @@ -195,12 +195,12 @@ HUD框架站在玩家与全部玩法系统之间：挖掘期它是输入的翻 |---|---|---| | 上游 | [排雷玩法](../排雷循环/排雷玩法.md) | 棋盘只读投影（格态、数字、封印印记、小人）与移动路径查询；玩家意图批次经组合根提交 | | 上游 | [行动经济](../排雷循环/行动经济.md) | 行动点 / 储备 / 相位只读值；刷新入口可用性预判加返回值兜底 | -| 上游 | [战斗结算](../战斗循环/战斗结算.md) | 明细流水是结算明细带的统一数据源（现行 9 类行封闭协议）；段序编排信号经组合根接线 | +| 上游 | [战斗结算](../战斗循环/战斗结算.md) | 明细流水 9 类行封闭协议（明细带已退役——流水消费面=日志落盘与回放对账，HUD 不再消费）；段序编排信号经组合根接线 | | 上游 | [敌人系统](../战斗循环/敌人系统.md) | 英雄与敌人的只读投影（血量、顺位、摇定动作〔技能标识·类型·名称〕、敌方增益、存活——经战斗结算呈现快照；敌人技能池定稿：当前拍/行动环进度字段拆除，池与权重不公开） | | 上游 | [增益状态](../战斗循环/增益状态.md) | 状态投影经战斗结算呈现面取得，零直读 | | 上游 | [地图战斗资源](../战斗循环/地图战斗资源.md) | 已开格奖励身份投影（只读回调，组合根注入）零直读 | | 上游 | [关卡节点地图](../冒险循环/关卡节点地图.md) | 节点链、当前节点、跨战斗生命携带的读数；胜利后推进 | -| 下游 | [战斗表现](../战斗循环/战斗表现.md) | 交付三区布局、明细带呈现位、敌人呈现语义（站桩形态）；它只叠加动画密度与演出 | +| 下游 | [战斗表现](../战斗循环/战斗表现.md) | 交付三区布局、敌人呈现语义（站桩形态）；它只叠加动画密度与演出（明细带呈现位随带退役，2026-11-10 用户裁） | | 下游 | [音频](音频.md) | 挂点事件源（明细行类型流、toast 触发）；MVP 无音频 | | 下游 | [教学引导](教学引导.md) | toast 与图例面板两个承载位——教学内容装进这两个容器 | | 下游 | [设置与本地化](设置与本地化.md) | 中文字体随包、按钮宽度等契约的消费方 | @@ -225,7 +225,7 @@ HUD框架站在玩家与全部玩法系统之间：挖掘期它是输入的翻 1. 进入战斗屏：三区同屏就绪，半秒内首格可点。 2. 挖掘期鼠标操作经单意图帧整批提交（唯一写路径，经组合根）。 3. 回执链：组合根重查只读面，界面字段级就地刷新。 -4. 轮末进入结算：棋盘区锁输入，明细带展开逐行兑现（战斗结算流水驱动）。 +4. 轮末进入结算：棋盘区锁输入，结算演出在棋盘与立绘上逐段兑现（战斗结算段序驱动；明细带已退役）。 5. 终局呈现（胜利 / 失败）伴随状态全清与储备清零反馈。 6. 关卡末清库反馈：义务载体 = 秘宝背包（关卡域库存——秘宝过渡形态机械惰性承载，投放渠道全退役后恒空；拆线归实装批，见[战斗结算](../战斗循环/战斗结算.md)「轮次生命周期」节注）。 @@ -244,7 +244,7 @@ HUD框架站在玩家与全部玩法系统之间：挖掘期它是输入的翻 ## 调参表 -本系统的参数全部是呈现节奏与可读性常量，不是玩法数值——玩法数值一律归[数据配置](数据配置.md)的表，与本表无关。修订本文常量走文档修订流程。**本表常量无数据表承载，为文档面唯一事实源；入驻 .tres 时本列改指路。** 布局几何（B 区高 / B 区连续地面层高 / C 区宽 / D 区侧栏宽 / 明细带两态高）已入驻 `game/data/tables/battle_layout.tres`，不在本表重复。 +本系统的参数全部是呈现节奏与可读性常量，不是玩法数值——玩法数值一律归[数据配置](数据配置.md)的表，与本表无关。修订本文常量走文档修订流程。**本表常量无数据表承载，为文档面唯一事实源；入驻 .tres 时本列改指路。** 布局几何（B 区高 / B 区连续地面层高 / C 区宽 / D 区侧栏宽 / 明细带两态高〔已不被游戏视图读取，字段删除归工具批〕）已入驻 `game/data/tables/battle_layout.tres`，不在本表重复。 | 参数 | 域 | 现行值（文档自持，无表承载） | 说明 | |---|---|---|---| diff --git a/design/ux/battle.md b/design/ux/battle.md index bae29a2a..50c4a432 100644 --- a/design/ux/battle.md +++ b/design/ux/battle.md @@ -2,7 +2,7 @@ > **Status**: Complete（现行） > **Author**: user + ux-designer -> **Last Updated**: 2026-11-09 +> **Last Updated**: 2026-11-10 > **Platform Target**: PC (Steam)——Keyboard/Mouse 主（全部操作纯鼠标可完成）、Gamepad Partial 非 MVP、Touch None（同 technical-preferences） > **上游修订依赖**: 弃图刷新挖掘期受理依赖上游现行规则（行动经济 Active 受理 + 每轮上限 2 次、排雷玩法 Active·仅刷新路径装板、战斗结算的挖掘期刷新编排 + 恒同盘不变、系统索引的刷新规则同步——见布局决策 4 与 OQ11） > **Template**: UX Spec @@ -100,7 +100,7 @@ - **B 区战斗画面** - 主角站桩：立绘、HP 血条、状态效果小图标行 ← **HP 与状态的唯一展示面**（2026-09-26 拍板：C 区同信息展示退役） - 敌人站桩 ×1–3：HP 血条、顺位徽标、状态小图标行、意图徽标、护甲类型图标（AC 数值不展示——2026-09-26 终裁） - - 兑现演出区 / 结算明细带 / 轮次·阶段指示 + - 兑现演出区 / 轮次·阶段指示（结算明细带已退役，2026-11-10 用户裁） - **C 区角色信息（规划数据框）** - 攻击值 + 修正来源角标（战斗在消费、且站桩上无展示） - 护甲 AC（2026-09-26 二轮拍板补入——我方 AC 的唯一展示面；掷点判定轴，受击侧可读性） @@ -115,11 +115,11 @@ ### Layout Zones -采用用户拍板的布局图（2026-09-12），按 1280×800 基座落尺寸。**分区几何的唯一事实源 = `game/data/tables/battle_layout.tres`**（经 `ConfigDb.presentation.battle_layout` 读取；字段 `stage_h` / `ground_h`（B 区连续地面层高）/ `info_panel_w` / `side_rail_w`（D 区行动资源侧栏宽，2026-11-07 顶栏搬两侧后新增）/ `log_band_h_dig` / `log_band_h_settle`；游戏视图不再读 `ap_bar_h`；布局表字段暂留供样张渲染工具，删除归工具批）。本节只写结构关系与内容职责，不复写数值；任何文档与代码不另立第二份布局值。 +采用用户拍板的布局图（2026-09-12），按 1280×800 基座落尺寸。**分区几何的唯一事实源 = `game/data/tables/battle_layout.tres`**（经 `ConfigDb.presentation.battle_layout` 读取；字段 `stage_h` / `ground_h`（B 区连续地面层高）/ `info_panel_w` / `side_rail_w`（D 区行动资源侧栏宽，2026-11-07 顶栏搬两侧后新增）/ `log_band_h_dig` / `log_band_h_settle`；游戏视图不再读 `ap_bar_h` 与 `log_band_h_dig`／`log_band_h_settle`（明细带退役，2026-11-10 用户裁）；布局表字段暂留供样张渲染工具，删除归工具批）。本节只写结构关系与内容职责，不复写数值；任何文档与代码不另立第二份布局值。 | 区 | 位置与几何 | 内容 | |---|---|---| -| **B 战斗画面** | 全宽，高读 `stage_h`（2026-10-06 方案二拍板：演出 ≈1/3 屏） | 主角站桩立绘（左）+ 兑现演出区（中）+ 敌人站桩立绘 ×1–3（右）——**全站桩形态（2026-09-20 用户拍板）：主角与敌人均为无框立绘+底座，零卡片**；主角与敌人站桩 = **HP 与状态效果的唯一展示面（2026-09-26 信息归属拍板）**；底部结算明细带（挖掘期收起高读 `log_band_h_dig`，结算期展开高读 `log_band_h_settle`）；顶部中央轮次·阶段指示 | +| **B 战斗画面** | 全宽，高读 `stage_h`（2026-10-06 方案二拍板：演出 ≈1/3 屏） | 主角站桩立绘（左）+ 兑现演出区（中）+ 敌人站桩立绘 ×1–3（右）——**全站桩形态（2026-09-20 用户拍板）：主角与敌人均为无框立绘+底座，零卡片**；主角与敌人站桩 = **HP 与状态效果的唯一展示面（2026-09-26 信息归属拍板）**；结算明细带已退役（2026-11-10 用户裁，B 区零文字带，规格见「即时反馈画面化预览」节）；顶部中央轮次·阶段指示 | | **C 角色信息** | 左下，宽读 `info_panel_w`，高 = 基准屏高 − B 区高 | 攻击值（含修正显示）、护甲 AC；秘宝槽、奇物列表（现行标题「特性」）——HP 条/RAP 池/状态效果槽/立绘占位/钱包行退役（2026-09-26 信息归属拍板：HP 与状态唯一展示面 = B 区站桩；RAP 迁 D 区右栏；GP/钥石迁出战斗屏） | | **D 扫雷图** | 中下，宽 = 基准屏宽 − C 区宽 − 列间距，高同 C 区（2026-11-07 顶栏搬两侧：**D 区全高归棋盘**，不再让出 AP 条高度；棋盘不缩，格边按公式现算） | 左栏（宽读 `side_rail_w`，贴棋盘左缘）：AP 点阵 + 停手按钮；右栏（同宽，贴棋盘右缘）：RAP 点阵+数字 + 图例按钮 + 弃图刷新按钮（RAP 贴唯一消费口，2026-09-26 拍板）；棋盘主体居中（格边长见下方「棋盘格尺寸公式」；上方留 44px 给浮空数字越出棋盘，下方 12px＋悬崖 8px）；toast 槽（D 区上缘内侧左栏顶部，不覆盖棋盘与浮空数字）；棋盘底常驻操作提示条退役（2026-11-07 用户裁，不占棋盘高度） | @@ -190,6 +190,69 @@ 算例不入文档：棋盘区可用面积随布局表与板型变化，不是契约值——现算并绘在整屏样张上，本文件不复写。 +### 即时反馈画面化预览（2026-11-10 用户裁：明细带退役＋清图兑付浮字＋Boss 解锁技零提示；三屏预览 2026-11-10 用户人审通过） + +**清图兑付浮字**：全图最后一块安全格开启的瞬间，在既有金粒喷泉＋彩纸（§2.3）之上，兑付内容以**单行浮字**自棋盘中央上方升起——只写兑付值（例：「全体敌人 14 伤害」），无「清图奖励」标题、无底牌、不遮棋盘任何格；替代退役前的「清图奖励：××」toast。浮字规格：字高 17px（基座档）、暖白字芯＋2px 深墨描边＋微金光晕，约 2.5s 内上浮约 40px 并渐隐，时序落在喷泉 3–5s 窗口内、先于换新图 install。 +像素判据：浮字全程不与棋盘格面重叠（浮字底缘恒在棋盘上缘上方 ≥6px）；渐隐连续无跳变（帧间 alpha 步进 ≤0.1）；兑付值在浮字生命期 ≥60% 时长内保持全可读。 + +**Boss 解锁技零提示**：解锁拍（Boss 血量跌破闩阈值）**不新增任何 UI 元素**——血条跌破本身即视觉事件，「我把它打到半血 → 它亮新招」因果自明；下一拍开轮摇中新技时，既有意图徽标（类型级预告，敌人系统 Rule 8⑤）按现行规格自然顶头，具名随预告承载。原「一次性技能名 toast」规格退役（[敌人系统](../gdd/systems/战斗循环/敌人系统.md) v2.1 同步改写）。 +像素判据：解锁拍 B 区新增可见元素数为 0（与前一帧逐元素比对）；意图徽标几何沿用现行规格（悬浮头顶上方、探顶档压胸），零新增资产。 + +**战斗屏纵向**：明细带退役后 B 区舞台（高读 `stage_h`）直连 D 区——挖掘期 D 区可用高 +24、结算期 +84，棋盘格边按「棋盘格尺寸公式」现算放大，公式与垂直预留（上 44 / 下 12）不变；`log_band_h_dig`／`log_band_h_settle` 不再被游戏视图读取。 + + + + + 清图兑付浮字 + 解锁拍（零新增） + 下拍开轮（意图徽标顶头） + + + + + + + + + + + + + + 全体敌人 14 伤害 + 浮字底缘恒在棋盘上缘上方 ≥6px + + + + + + + + 探险者 + + + 石君王 42% + （无任何新增元素） + 血条跌破即视觉事件 · B 区新增元素数 = 0 + + + + + + + + 探险者 + + + 石君王 + + ⛰ + + 岩崩 + 既有意图徽标规格 · 几何零改动 + + + ### Component Inventory | 区 | 组件 | 类型 | 内容 | 交互 | 载体 | @@ -197,8 +260,8 @@ | B | 主角站桩立绘 | 站桩（无框立绘+落影） | HP 条落底盘（2026-10-06 方案二拍板：站桩排式 = **立绘→血条→状态**，全场血条对齐一线；血条嵌石板位、台缘线留作地面线；不悬浮头顶——高盒下血条-立绘空洞，用户点名否决）、状态效果小图标一排挂血条正下方（形状+色相双通道、层数角标；空态不占位退化为空行）——**HP 与状态效果的唯一展示面（2026-09-26 信息归属拍板；悬停 tooltip〔来源+语义+剩余结算次数〕职责在本组件）**；攻击值等规划数据仍归 C 区数据框（2026-09-20 全站桩拍板，英雄卡退役） | 悬停状态小图标看 tooltip | HUD 视图拆分改造 | | B | 敌人站桩立绘 ×1–3 | 站桩（无框立绘+落影） | 血条+顺位徽标落底盘（同主角排式，2026-10-06 方案二；**大体档〔显示 >150px 级：drider/duergar_king〕允许向上溢出盒顶 N px（N 由实装实算，溢出判定与背景无关），血条仍落底**）、状态小图标挂血条正下方（敌方增益按个体呈现——各立绘只显示它自己名下的状态实例〔蓄力/硬化/削弱/暴走/警觉，2026-11-02 个体化裁〕；数据源 = 战斗结算流水经增益状态投影，敌人系统×4④；无行为环点〔proposal §2.4〕，意图占位 = 本拍摇定结果的动画占位——普通攻击零表示 / 特殊技类型级提示，**意图徽标悬浮头顶上方，探顶档压胸**，敌方增益〔蓄力/硬化〕入状态图标行）；死亡灰化加碎裂退场直接演在立绘上（2026-09-20 全站桩拍板，敌人卡退役）；血条下名字行 = 纯名字 + 护甲类型图标（形状+色相双通道，与状态图标同行共存，状态空时为纯名字），AC 数值不展示——2026-09-26 终裁（用户口径：HP 信息已足够，攻防数值不直接写上；护甲类型图标保留克制对策可读性——类型可读、数值隐藏） | 只读 | 新建 | | B | 轮次·阶段指示 | 标签 | "第 N 轮 · 挖掘中/结算中"（终局定格「战斗结束」；Boss 变体附 Boss 名） | 只读 | 新建 | -| B | 结算明细带 | 摘要位＋叙述行 | 逐行流水文字呈现已退役（2026-11-07 用户裁）：挖掘期显示上轮摘要 1 行与冒险叙述行，结算期空带＋FX 排播链承接演出；流水协议保留在数据面（[战斗结算](../gdd/systems/战斗循环/战斗结算.md#明细流水每一行都能指回你刚才的哪一步棋) 9 类行协议，供日志落盘与回放对账） | 无明细回看——带保留单行摘要，冒险中回看归「生涯」 | 改造 | -| B | 结算明细回看（已退役） | —— | 冒险中回看归「生涯」；回看覆盖层为未接线遗留件（待办清单登记） | —— | 未接线 | +| B | 结算明细带（已退役） | —— | 明细带整条退役（2026-11-10 用户裁）：挖掘期摘要位为恒空死区（写入函数随 2026-11-07 逐行退役批删除）、冒险叙述行对玩家零信息增量——舞台底高归还（挖掘期 +24 / 结算期 +84 归 D 区棋盘区，格边按「棋盘格尺寸公式」现算）；冒险叙述行六类随带全砍——关卡开场数字归 C 区数据框（同值重复）、恢复点回血归节点弹窗、商店 GP 归商店浮层、钥石结算归胜负浮层账行、节点横幅与岔路口文字砍（节点类型与可选交互自明）；逐行流水文字呈现此前已退役（2026-11-07 用户裁）；流水协议保留在数据面（[战斗结算](../gdd/systems/战斗循环/战斗结算.md#明细流水每一行都能指回你刚才的哪一步棋) 9 类行协议，供日志落盘与回放对账） | —— | 退役 | +| B | 结算明细回看（已退役） | —— | 冒险中回看归「生涯」；回看覆盖层为未接线遗留件，与明细带同批报废（2026-11-10 用户裁） | —— | 退役 | | C | 攻击数据框 | 直角细线数据框 | 攻击值 + 修正来源角标 + 护甲 AC（AC 二轮拍板 2026-09-26 补入——我方 AC 唯一展示面；HP 与状态归 B 区站桩、RAP 归 D 区右栏，不在本组件） | 只读 | HUD 视图拆分 | | C | 秘宝槽 | 图标槽 ×4 | 四槽壳在役、空槽占位（标题「秘宝」，悬停「秘宝槽（空）」）；局内两步使用与关卡域库存随秘宝过渡形态退役——现行秘宝 = 营地同调装配件（秘宝.md），本区展示重接归装配面 | 悬停 tooltip | 已实装 | | C | 奇物列表（现行标题「特性」） | 列表/图标行 | 已实装——逐件行「件名 ×N」呈现、零内部分类字样；锻造/大奖励/关卡奖励节点获得的属性提升——中循环数据，因改变战斗数学且无其他展示面准入战斗屏；与战斗内状态效果（B 区站桩）分区，防「战斗结束被清」误读 | 只读 | 已实装 | @@ -247,9 +310,7 @@ │ （落影） [ 兑现演出区 ] /蛆虫\ /蛆虫\ │ │ HP▓▓▓▓░ (结算期: 光带→弹道→受击) ①HP▓▓▓░ ②HP▓▓░░ │ │ ⬆2 🛡1 ←血条状态落底排·全场对齐（状态空 = 名字行）〔意图徽标悬浮头顶上方〕 │ -│ ├─ 结算明细带 ────────────────────────────────────────────────────────────┤ │ -│ │ ▸上轮: 主角攻击3→蛆虫-3 | 攻击+50%(1结算) | 警觉+1×2 … │ │ -│ └────────────────────────────────────────────────────────────────────────┘ │ +│ （明细带已退役——舞台直连 D 区，挖掘期 +24 / 结算期 +84 归棋盘区） │ ├─[C] 角色信息 ─────────┬─[D] 扫雷图（顶栏已搬两侧） ───────────────────────────┤ │ ┌──────────────────┐ │ ┌──────┐ ┌───────────────────────────┐ ┌──────┐ │ │ │ 攻击 6 (+50%) │ │ │ AP │ │ (上方 44px 留白) │ │ RAP │ │ @@ -361,8 +422,8 @@ | State / Variant | Trigger | What Changes | |---|---|---| | **挖掘阶段（默认态）** | 轮次开始 / 结算完毕回 Active 相位 | B 区敌人待机（意图徽标全程可见——敌人系统 Rule 8⑤），D 区棋盘可交互，左右行动资源侧栏点亮；能量 2/10，唯悬停呼吸微光在动（§2.1） | -| **结算阶段** | round_end 触发（AP 尽/停手/清图） | D 区锁输入（棋盘去饱和 + 金橙色相偏移，明度不变，数字保持全对比）；B 区播放五段编排演出（授予段 → 增益/减益段 → 战斗段 → 衰减段 → 判定段，战斗结算 段序冻结）；明细带按结算期档展开（高读 `log_band_h_settle`）——settle 态空带＋叙述行承载，零逐行文字；阶段指示→"结算中"；能量 7/10 | -| **清图瞬间** | 全部安全格开完 | 金粒喷泉 + 彩纸 3–5s 即收（§2.3）；清图奖励行强调呈现（H2，地图战斗资源×④——金框高亮行）；随后换新图 install | +| **结算阶段** | round_end 触发（AP 尽/停手/清图） | D 区锁输入（棋盘去饱和 + 金橙色相偏移，明度不变，数字保持全对比）；B 区播放五段编排演出（授予段 → 增益/减益段 → 战斗段 → 衰减段 → 判定段，战斗结算 段序冻结）；明细带已退役——结算演出全程在棋盘与立绘上，零文字带；阶段指示→"结算中"；能量 7/10 | +| **清图瞬间** | 全部安全格开完 | 金粒喷泉 + 彩纸 3–5s 即收（§2.3）；兑付浮字随喷泉升起——只写兑付内容（如「全体敌人 14 伤害」），无标题、无底牌、不遮棋盘（规格与像素判据见「即时反馈画面化预览」节）；随后换新图 install | | **完美封印高光** | 战斗结算高光判定（全图标中/零误标类） | 全屏喝彩级反馈（§2.2 最高档）：金光带加倍扫射 + 「完美封印 ×2」横幅——P2 爆发兑现节点（创意风险 #2 落点） | | **封印标中高光** | 封印判定·标中 | 该印记化暴击弹道加重 + 明细行金框——chord 缺席的即时兑现补偿（创意风险 #3 落点） | | **敌人死亡呈现** | 敌 hp=0（流水行击杀标记） | 该敌人立绘血条归零 → 立绘灰化 + 碎裂退场（**禁瞬消**——敌人系统资产下限「死亡瞬间须可辨识、禁止直接消失」，同等 blocking）；战斗段短路的重击被掐灭不产行动明细行，由行序可推断（战斗结算）；动画密度归战斗表现，呈现语义在本 spec | @@ -428,7 +489,7 @@ | 时刻 | 过渡 | 依据 | |---|---|---| | 进入战斗屏 | 棋盘 install 淡入（200ms）+ 初始 3×3 展开涟漪 + Boss 战先播紫赤影子爬棋盘（§2.6） | 棋盘生成 install / §2.6 | -| 挖掘→结算 | 明细带自底展开（150ms）+ 棋盘去饱和 + 金橙色相偏移 + 阶段指示翻转 | §2.2 色彩转金橙主导、饱和拉高、明度不变（状态区分经饱和/色相——art-bible §2） | +| 挖掘→结算 | 棋盘去饱和 + 金橙色相偏移 + 阶段指示翻转 | §2.2 色彩转金橙主导、饱和拉高、明度不变（状态区分经饱和/色相——art-bible §2） | | 结算逐行兑现 | 光带自棋盘行起点横扫 → 开格化箭雨/印记化暴击弹道飞向敌人立绘 → 受击闪白 + 血条直角递减 | §2.2 承载元素；因果全程可见可归因（P2） | | 清图换新图 | 金粒喷泉 3–5s → 旧图碎裂淡出 → 新图 install 淡入 | §2.3 短促丰收不拖节奏 | | RAP 清零（冒险收束） | RAP 数字滚动归零（D 区右栏）+「随冒险结束消散」微文案 | 行动经济可见反馈义务 | @@ -483,7 +544,6 @@ - **源语言中文（CJK）**：运行时默认字体无 CJK 字形——**CJK 字体随包为硬性前置**（已锁），实现 AC 覆盖 - **按钮文案单行约束**：「停手」「弃图刷新」——按钮宽度按 4 汉字上限设计；译为英文（"Hold"/"Reroll"）不超 1.6× 不破版；德语长词（"Aufgeben+Neu"类复合词）风险 HIGH——弃图刷新按钮允许两行或图标+缩写 -- **明细带行文案**：来源标注格式「{行为} {值} → {目标}（来源）」为模板插值，最长 token = 来源标签（4 汉字，如「清图奖励」「封印未中」——战斗结算的来源标签封闭枚举）；行模板预留 40% 膨胀宽度（固定槽高 + 裁剪兜底） - **数字格式**：全部整数，无本地化格式需求；AP 点阵为图形载体不依赖文本 - **术语表锚定**：封印/雷/停手/弃图刷新/轮次/结算 已在 GDD 体系内定名，译文须同步 `design/gdd/术语表.md` diff --git a/game/tests/README.md b/game/tests/README.md index 07a0d01e..a7323632 100644 --- a/game/tests/README.md +++ b/game/tests/README.md @@ -159,13 +159,19 @@ tests/ | 敌方意图徽标类型级预告 | 战斗表现 | `StandeeBody.set_pending()` → `StandeeBody.intent_probe()` | `standee_fx_sweep_test.gd:_init` | | B 区舞台背景三关变体与连续地面层（按 board_type 选图／地面层高度读布局表／四柱光柱退役） | HUD框架 | `BattleStageView.set_board_type()` | `stage_background_test.gd:_test_background_selection`；`stage_background_test.gd:_test_ground_layer_geometry`；`stage_background_test.gd:_test_beams_retired` | | 动画帧数规格（待机/攻击/受击；现役单帧形制锚定） | 战斗表现 | `UiKit.load_tex()`（`TEX_HERO_*` 四态件装载链——棋盘站立/行走与舞台三态同源） | `animation_frame_spec_test.gd:_test_spec_table`；`animation_frame_spec_test.gd:_test_current_form` | -| 战斗屏三区几何与棋盘格边长（分辨率两档×四档板型） | HUD框架 | `BoardView.set_cell_area()`（D 区可用面积 → 格边长）；读面 `BoardView.cell_size` | `layout_probe.gd:_ready`；`board_gen_reward_test.gd:_smoke_layout_cell_formula`；`stage_background_test.gd:_test_side_rail_width_from_table`／`_test_log_band_settle_height`（计划——需求卡片「QA覆盖余量收口批」2026-11-07 锚定） | +| 战斗屏三区几何与棋盘格边长（分辨率两档×四档板型） | HUD框架 | `BoardView.set_cell_area()`（D 区可用面积 → 格边长）；读面 `BoardView.cell_size` | `layout_probe.gd:_ready`；`board_gen_reward_test.gd:_smoke_layout_cell_formula`；`stage_background_test.gd:_test_side_rail_width_from_table`（`_test_log_band_settle_height` 计划用例随明细带退役作废——需求卡片「明细带退役呈现改版批」2026-11-10） | | 调参测速批量模拟（逐帧步进与统计读数） | 调参测量 | `TuneSimController.run()`（调试浮窗批量模拟入口） | `tune_sim_batch_parity_test.gd:_init`（配对对拍套件） | | sim 驱动循环单点（缺省零变化与策略/日志回调形态） | 调参测量 | `BattleDriver.drive_round()`（两参缺省与五参回调两形态） | `battle_driver_drive_test.gd:_smoke_drive_round_contract` | | 模拟玩家 0 格连锁算子（经真实闭包，零盲挖语义保持） | 调参测量×排雷玩法 | `AutoPlayer._deduce()`（经 `perfect_action()` 装配链） | `auto_player_deduce_test.gd:_smoke_zero_chain_rule` | | 刷新提示文案读表拼接（RAP 不足／轮上限两 toast 零字面量） | HUD框架 | `Main._on_refresh_confirmed()`（两 toast 装配面）＋`player_copy_sweep` 源扫描 | `player_copy_sweep_test.gd:_sweep_refresh_toast_no_literals` | | 试玩日志器 ap_per_round 必填注入守卫（未注入拒绝开会话） | 表现与支撑 | `PlaytestLogger.start_session()` | `playtest_logger_guard_test.gd:_smoke_required_injection` | -| 战斗叙述与终局文案（数值带入／胜负互异） | HUD框架 | `BattleNarrator.battle_end_text()`／`BattleNarrator.boss_name()` | `battle_narrator_test.gd:_test_numeric_lines_carry_values`；`battle_narrator_test.gd:_test_end_text_differs_by_result`；`battle_narrator_test.gd:_test_boss_name_uses_boss_rowset` | +| 终局判定文案与战末账行 | HUD框架 | `BattleEndOverlay.open_victory()`／`open_defeat()`（verdict_line 由组合根直拼传入） | `ui_click_probe.gd:_ready`（终局浮层段） | +| B 区零文字带 | HUD框架 | `Main._ready()`（组合根场景树装配）＋节点推进/恢复/商店/终局真实流 | `log_band_retired_test.gd:_test_no_log_view_node`；`log_band_retired_test.gd:_test_b_zone_zero_text` | +| 清图兑付浮字 | HUD框架 | `BoardZoneView.spawn_clear_reward_text()`（round_end clear 分支装配） | `clear_reward_text_test.gd:_test_spawn_and_decay`；`clear_reward_text_test.gd:_test_no_overlap` | +| 解锁拍零新增呈现 | HUD框架 | `RowPacer.enqueue()`→`consume_now()`（skill_unlock 高光行消费流，快照取消费时刻） | `unlock_zero_ui_test.gd:_test_zero_delta` | +| 文案承载单点 | 数据配置与跨系统契约 | `TranslationServer.set_locale()` 后场景 `Label.tr()` 真实查表 | `player_copy_sweep_test.gd:_sweep_tr_roundtrip` | +| 表行文案 key 化 | 数据配置与跨系统契约 | `ConfigDB._ready()`（autoload 加载真实表＋schema 校验闸） | `config_table_key_test.gd:_test_display_key_format` | +| 文案漏网清零 | 数据配置×表现与支撑 | `Main._ready()`（组合根装配链全量加载）＋`player_copy_sweep` 源扫描 | `player_copy_sweep_test.gd:_sweep_zero_product_literals` | | 玩家面文案与危险格格面字形 | HUD框架 | `BoardView.rebuild()`／`StatusSlotRow.set_effects()` | `player_copy_sweep_test.gd:_sweep_board_glyph`；`player_copy_sweep_test.gd:_sweep_legend`；`player_copy_sweep_test.gd:_sweep_hero_panel` | | 营地场景图十层铺底与门洞留空呈现 | 营地场景视图 | 进入存档→选档→进档→营地场景屏（`CampSceneView.setup_layers()` 驱动）；单元测试载入 `camp_scene_layout.tres` | `shot_probe.gd:_ready`（camp 截图段）；`camp_scene_layout_test.gd:_test_layout_hotspot_geometry` | | 营地七物件命中区点选与分界面可达 | 营地场景视图 | 七物件命中区 → 合成鼠标事件经 `push_input` 真点（`ProbeUiUtil.push_click_at` 热点中心）→ `CampSceneView._gui_input()`（命中发 `object_pressed` 信号） → 组合根开界面（2026-11-06 真输入化，残险登记撤） | `ui_click_probe.gd:_ready`（七物件合成点击段——真输入驱动） | @@ -230,7 +236,7 @@ tests/ | 排雷循环 | 排雷玩法.md | 装板与开局免费展开（封锁格无资源、计入清图）；挖／封印合法性与可辨拒绝（拒绝零副作用、挖封印格被拒）；封印受理即揭示（身份可查、受理零事件）；清图口径换代（挖开∪封印、封印可完成清图） | 已覆盖 | — | | 排雷循环 | 棋盘生成.md | 棋盘按参数行出图、数字恒真；同参数同种子逐位复现、异种子不退化；出板检查（出生区无雷／开局不全开、白给板同流重摇、指标集换代）；棋盘可推理率离线测量（仅 sim，不入生成管线） | 已覆盖 | — | | 排雷循环 | 行动经济.md | AP 扣费、末点耗尽即收轮与战斗收束清零；停手转存储备与轮内刷新（上限／AP 不重置／刷新图零清图奖励）；下轮行动点修正排队与兑现 | 已覆盖 | — | -| 表现与支撑 | HUD框架.md | 拒绝反馈分面可辨与未知兜底文案；结算期零逐行文字与 FX 排播链保持；模态覆盖层编排与输入锁；未开格类型微光（8 邻作用集、五组色相、零玩法写入）；UI 全局主题与按钮五态（含对比度锚）；中文字体随包与字形覆盖；地形瓦片套与格面数字可读（旧行保留，删行归写卡段后续，实现批禁写）；棋盘合并岩体与连续地面（深度遮挡、投影、崖面）；棋盘浮空数字与引导线（最顶层、顶部预留）；D 区行动资源侧栏（AP 左栏、RAP 右栏、全高棋盘）；棋盘点击命中与格边公式（逻辑格矩形）；旧瓦片退役与普通数字零底牌；棋盘顶面锚点与迷雾几何（微光、变异岩顶偏移，封印格心）；战斗叙述与终局文案（数值带入／胜负互异）；玩家面文案与危险格格面字形；战斗屏三区几何与棋盘格边长（分辨率两档×四档板型）；B 区舞台背景三关变体与连续地面层（按 board_type 选图／地面层高度读布局表／四柱光柱退役）；模态句柄分域寻址面 | 已覆盖 | — | +| 表现与支撑 | HUD框架.md | 拒绝反馈分面可辨与未知兜底文案；结算期零逐行文字与 FX 排播链保持；模态覆盖层编排与输入锁；未开格类型微光（8 邻作用集、五组色相、零玩法写入）；UI 全局主题与按钮五态（含对比度锚）；中文字体随包与字形覆盖；地形瓦片套与格面数字可读（旧行保留，删行归写卡段后续，实现批禁写）；棋盘合并岩体与连续地面（深度遮挡、投影、崖面）；棋盘浮空数字与引导线（最顶层、顶部预留）；D 区行动资源侧栏（AP 左栏、RAP 右栏、全高棋盘）；棋盘点击命中与格边公式（逻辑格矩形）；旧瓦片退役与普通数字零底牌；棋盘顶面锚点与迷雾几何（微光、变异岩顶偏移，封印格心）；终局判定文案与战末账行；B 区零文字带；清图兑付浮字；解锁拍零新增呈现；玩家面文案与危险格格面字形；战斗屏三区几何与棋盘格边长（分辨率两档×四档板型）；B 区舞台背景三关变体与连续地面层（按 board_type 选图／地面层高度读布局表／四柱光柱退役）；模态句柄分域寻址面 | 已覆盖 | — | | 表现与支撑 | 存档序列化.md | 存档写盘⇄读回往返保真；三槽位隔离与激活失败回滚；槽位摘要窥视与坏槽三态；启动态无激活不写盘；旧档迁移链与断点续玩零跳号；存档⇄RNG 快照往返保真 | 已覆盖 | — | | 表现与支撑 | 教学引导.md | — | 未覆盖 | 教学形态与首遇时机待设计；见待办清单「教学形态未定」条 | | 表现与支撑 | 数据配置.md | 全表装载、就绪态与表清单目录对账；进度坐标查行：精确命中／向上取整／封顶／警告去重；运行期越域致命与进程非 0 退出；加载期违规表拒绝：跨表悬空／计数器前缀／真视窄域；表结构守卫：域校验／行序键／跨字段互锁／配额锚 | 已覆盖 | — | diff --git a/reports/需求卡片-文案入表批-2026-11-10.md b/reports/需求卡片-文案入表批-2026-11-10.md new file mode 100644 index 00000000..f1ca35b0 --- /dev/null +++ b/reports/需求卡片-文案入表批-2026-11-10.md @@ -0,0 +1,167 @@ +# 需求卡片：文案入表批（文案承载实装） + +- 来源：待办清单「结算明细文案入表」（2026-11-07 登记，来源=批次移交）（唯一事实源：design/engineering/code-conventions.md §2.5「玩家可见文案承载」＋design/gdd/systems/战斗循环/战斗结算.md v2.1 :87＋design/gdd/术语表.md v1.30「文案承载」节） +- 验收档：高（牵数值表结构与 schema 校验改名——存档无关但表结构校验面整体触改，按最高档申报） +- 基线声明：本卡现状面以「明细带退役呈现改版批」合入后终态为基线（该卡删六类叙述行/两 toast，本卡不再迁它们）；两卡同批编排时本卡排后，跨批时 T0 先核面 + +## 1. 目标与完成定义 + +文案承载换代实装：strings.csv 建立＋翻译管线注册；数据表行文案字段 key 化（display_name→display_key、desc→desc_key，值迁 strings.csv）；core 结算行 display 拼装改 key 发射；呈现层残余玩家可见文案全部经 tr() 取用；场景静态文案 key 化；漏网字面量 grep 断言清零。完成定义＝对照表 W1–W6 全绿＋代码域闸绿＋产品码玩家可见文案字面量 grep=0。 + +## 2. 现状事实（file:line 实查） + +- 翻译管线现状＝零：project.godot 无 internationalization 配置（grep 零命中；默认 locale=en——注册 zh_CN 翻译后须同批设 locale/fallback，否则 tr() 按 key 原样返回）；`tr(`/`atr()` 在 game/presentation 与 game/core 零使用。 +- 数据表文案值：game/data/tables/*.tres 含中文字段值约 220 个——display_name 162、desc 48、name_a/name_b 6、settlement.tres source_label_map 7 值（:9 起）；另有 493 行中文为表内 `;` 注释（不迁）。 +- schema 键面：「display_name 空/为空」校验实查 13 处/11 件（feat:37、skill:67、status_effect:49、enemy:96、treasure_item:90、hero:23、meta_tree/level/reward/variation/shop 六件同类）；键集同步面 4 处：feat_table.gd:16（ROW_KEYS）、meta_tree_table.gd:17（KEY_WHITELIST）、forge_table.gd:16（ROW_KEYS）、treasure_item_table.gd:50（KEY_WHITELIST），另 hero_table.gd:11 默认值——五处随键改名全数同步。 +- core 结算行 display 拼装：core/settlement/grant_segment.gd:73/294（「专长·GP 入账 +%d」）/:318（「坑道小憩 未生效（满血）」）/:321/:333/:399/:414/:438/:441（「封印未中」）等约 15 处、core/damage_controller.gd:397/425（「＋奥术%d（必中）」等）/483/508/515/533、core/settlement/verdict_segment.gd:38/42（「战斗失败/胜利」）、core/settlement/round_cycle.gd:109（「%s 解锁了 %s」）。 +- 呈现层残余文案（明细带退役批合入后，实测约 43 处级）：camp_shop_presenter.gd show_toast 11 处、treasure_interact_controller.gd 5 处（:92/:110 读 rec.get("name"/"display_name")）、curio_interact_controller.gd 4 处＋:79（「继续」）/:137（「专长获取…」）等、main.gd 9 处（:421 清图 toast 已由退役批改浮字装配）＋:367（「第 %d 层通过！…」）/:374/:378/:381（终局按钮字串，退役批改写面）/:453/:497/:502、main_adventure_flow.gd 1 处＋终局字串 4 处（:113「返回冒险」/:114「本局 GP 入账 · 合计 %d」/:181「战利品 GP +%d · 合计 %d」/:179「下一节点」）＋:116/:231/:233/:241（「返回」「攻 +%d」「上限 +%d」「攻击 %s · 护甲 AC %s」）、views/node_overlay.gd 3 处（:20/:27/:29）、views/battle_end_overlay.gd:230/:231 固定名「战利品 GP」、main.gd:404 ks_summary「钥石 · 累计 %d」＋HudPresenter.gp_summary_text/bonus_summary_text＋hud_presenter.gd:344 phase_text 阶段指示文案组（退役批直连后落地所在）、views/status_slot_row.gd:40 SOURCE_NAMES、退役批新增的浮字装配字串 1 处。 +- 场景静态文案：复核实证 game/ 全部 22 个 .tscn 中文字符=0（呈现层中文实际在 .gd 动态装配，归上方呈现层面）——无独立场景迁移面，W5 降为核验行。 +- 退役批基线：views/board_zone_view.gd `spawn_clear_reward_text(text: String)` 在役（浮字文案由装配处传入）。 + +## 3. 设计契约 + +- 🔴 文案值单点：玩家可见文案值只住 game/data/l10n/strings.csv（key 列＋zh_CN 列）；代码、数据表行、场景文件零文案字面量（code-conventions §2.5）。 +- 🔴 key 模板：点分 `<表域>.<行id>.`（表行）／`<界面域>.<用途>`（界面文案）；全库唯一，登记于 strings.csv；禁两处同名异值。 +- 🔴 core 层只发 key 不取文案：结算行 display 字段值改 display_key（行协议字段形态变更已由战斗结算 v2.1 覆盖）；core 禁 import 翻译服务取中文。 +- 🔴 schema 改名同步：display_key/desc_key 进各表 ROW_KEYS/KEY_WHITELIST，空校验改 key 格式校验（非空＋点分），禁保留旧键双轨。 +- 🔴 日志落盘零文案不变：text/display 不落盘边界（战斗结算 v2.1）不因本卡改动。 +- 🔴 禁变异测试与撤销取证：字面量清零断言用产品码静态 grep（真实闸跑批），禁「先迁走再改回」式取证。 + +## 4. 范围边界 + +做：上列管线建立、三处迁移（表行/core 行/呈现层）、场景 key 化、漏网清零断言、能力表同批维护。 +不做（去向）：诊断文案（push_error/assert/日志）与 sim/probe/tests 文字（code-conventions §2.5 豁免面）；493 行 .tres 注释；静态扫描闸新增 S 规则（tools/ 面＝工程改动直改类，登记待办清单另行批）；多语言（语言列扩展归设置与本地化后置）；UI 呈现观感（零视觉变化，golden 基线不受影响——场景 text 值渲染结果逐像素不变）。 + +## 5. 关联文档同步面 + +| 文档 | 关联点 | 同步义务 | +|---|---|---| +| game/data/tables/*.tres（18 张） | display_name/desc 值迁出 | 本批实现直接改（数据件非 design/） | +| design/gdd/systems/战斗循环/战斗结算.md | :87 行公共字段「显示名」提法与 display_key 形态核 | 实现批列反哺点（v2.1 已写「数据表行只登记文案 key」，实现核对提法一致性） | +| design/gdd/术语表.md | 文案 key 词条的 key 模板句核对 | 实现批列反哺点 | +| game/tests/README.md | 能力行增删 | 本卡写卡段执行 | +| design/ux/battle.md | 浮字文案来源句（暂字串→tr） | 实现批列反哺点 | + +## 6. 卡前·文件结构图 + +| 文件 | 职责 | 行为改动 | +|---|---|---| +| game/data/l10n/strings.csv | 新增：文案值唯一承载（key,zh_CN 两列＋表头） | 是（W1） | +| game/project.godot | 翻译资源注册（internationalization/translations） | 是（W1） | +| game/data/tables/*.tres（18 张） | display_name→display_key、desc→desc_key，值改 key | 是（W2） | +| game/data/schemas/ 十一件 | 键改名＋key 格式校验（13 处「display_name 空/为空」校验全集＋键集同步面五处） | 是（W2） | +| game/core/config_db.gd 及读取面 | display_name 读取改 display_key（透传 key，取文案归呈现） | 是（W2） | +| game/core/settlement/grant_segment.gd、damage_controller.gd、verdict_segment.gd、round_cycle.gd | display 拼装改 key 发射（插值数字留数值字段） | 是（W3） | +| game/presentation/ 五控制器/Presenter＋views（toast/账行/SOURCE_NAMES/浮字装配） | 字面量改 tr("KEY") | 是（W4） | +| game/presentation/views/battle_end_overlay.gd | 固定名「战利品 GP」改 tr | 是（W4） | +| game/tests/unit/presentation/player_copy_sweep_test.gd | 扩展三函数（_sweep_tr_roundtrip/_sweep_no_literal_toast/_sweep_zero_product_literals——复用既有扫描件，见 §12） | 是（W1/W4/W6） | +| game/tests/unit/core/config_table_key_test.gd | 新增：表行 key 格式断言（W2） | 是 | +| game/tests/README.md | 能力行同批维护（写卡段执行，已入表） | 否 | + +## 7. 任务卡 + +### T0 管线建立（0.5 日） +- [ ] 新建 game/data/l10n/strings.csv：表头 `keys,zh_CN`＋首批 3 个探路 key（含 1 个带 %d 占位） +- [ ] project.godot 注册翻译资源（设置键 `internationalization/locale/translations`）＋**locale 设定**（`internationalization/locale/fallback` 或 test 默认 `TranslationServer.set_locale("zh_CN")`——缺此步 tr() 按 key 原样返回，W1 必红） +- [ ] 冒烟断言：一个探路 Label 经 tr() 取到中文（player_copy_sweep_test.gd:_sweep_tr_roundtrip 首个用例） +- [ ] 接口产出：strings.csv 路径常量 `STRINGS_CSV_PATH`（归 T4 闸用） + +### T1 数据表行 key 化（1–1.5 日） +- [ ] 18 张 tres：display_name/desc/name_a/name_b/source_label_map 值改 key（模板 `<表域>.<行id>.<字段>`），中文值迁 strings.csv +- [ ] 十一 schema：键改名＋「display_name 空/为空」13 处校验改 key 格式（非空＋含 `.`）；键集同步面五处（feat:16/meta_tree:17/forge:16/treasure_item:50/hero:11）全数改 +- [ ] ConfigDB 与全部读取面改读 display_key；呈现消费点改 `tr(row.display_key)` +- [ ] schema 校验闸＋表驱动单元全绿 +- [ ] 接口产出：无新签名（键名替换）；验证：单元全套件 + +### T2 core 行 key 化（0.5–1 日） +- [ ] grant_segment/damage_controller/verdict_segment/round_cycle 的 display 拼装字串改 key 常量（`const DISPLAY_KEY_*`），插值数字留原数值字段 +- [ ] 单元断言：结算行 display 值全库无中文字符（新用例挂 battle_settlement 套件） +- [ ] 接口取用：无；产出：DISPLAY_KEY_* 常量名清单（T3 无消费、登记待办供生涯批取用） + +### T3 呈现层迁移（1–1.75 日） +- [ ] 残余玩家可见文案约 43 处级改 tr("KEY")——清单以 §2 现状事实为唯一依据（camp_shop 11/curio 4＋2/treasure 5/main 9＋6/adventure_flow 1＋8/node_overlay 3/battle_end 2/ks 与 HudPresenter 3＋phase_text 组/SOURCE_NAMES 1/浮字 1） +- [ ] 带插值的字串：tr 取模板后 `%` 格式化（tr("camp.buy_denied") % 值形态） +- [ ] 接口取用：strings.csv（T0）；验证：单元＋冒烟 + +### T4 漏网清零与收口（0.5 日） +- [ ] player_copy_sweep_test 扩展静态断言 _sweep_zero_product_literals：grep 产品码三目录（core/data/presentation）非豁免文件的玩家可见中文字面量=0（诊断文案按 §2.5 豁免词法：push_error/assert/push_warning/_diag 行白名单）；.tscn 面纳入扫描词法（实证现值 0，防回归） +- [ ] 编辑器生成 POT 核对漏网（手动步，读数进实现报告） +- [ ] 产出物落位卡：reports/iter-实现报告、反哺点清单（同步面 5 行） + +估时合计：3.5–5.25 日（中值 4.375）。 + +## 8. 验证闸（改动—验收对照表） + +| 需求点 | 改动（文件:行为） | 验收测试 | 层级 | 真实入口 | 判据绑定面 | 能力行 | +|---|---|---|---|---|---|---| +| W1 管线端到端 `design/engineering/code-conventions.md「2.5 玩家可见文案承载」文案值只住` | strings.csv＋project.godot 翻译注册＋locale 设定 | player_copy_sweep_test::_sweep_tr_roundtrip | 单元 | 场景 Label 实例化 | tr("探路key") 返回值=csv 中文列值 | 新增：文案承载单点 | +| W2 表行 key 化 `design/engineering/code-conventions.md「2.5 玩家可见文案承载」数据表文案字段更名` | 18 tres＋十 schema | config_table_key_test::_test_display_key_format＋schema 校验闸 | 单元 | ConfigDB 加载真实表 | 行键名=display_key/desc_key＋值点分格式＋旧键 grep=0（十件全集） | 新增：表行文案 key 化 | +| W3 core 行 key 化 `design/gdd/systems/战斗循环/战斗结算.md「明细流水」数据表行只登记文案 key` | 结算四件 display 发射 | battle_settlement 套件新用例 | 单元 | 真实结算流（round_end 驱动） | 发射行 display 值无中文字符 | 既有：表行文案 key 化 | +| W4 呈现层迁移 `design/engineering/code-conventions.md「2.5 玩家可见文案承载」取文案只经` | toast 33 处/账行/SOURCE_NAMES/浮字/node_overlay | player_copy_sweep_test::_sweep_no_literal_toast | 单元 | 真实 UI 交互流 | show_toast/tr 调用点字面量 grep=0 | 既有：玩家面文案与危险格格面字形 | +| W5 场景文案核验 `design/engineering/code-conventions.md「2.5 玩家可见文案承载」场景静态` | .tscn 静态中文核验（复核实证 game/ 22 个 .tscn 中文=0——动态装配中文已归 W4 面） | 渲染闸 golden 比对＋_sweep_no_literal_toast 场景面 | 探针＋单元 | 渲染闸跑批 | 逐像素不变；.tscn 中文字面量=0（断言纳入 W6 扫描词法） | 既有：文案漏网清零 | +| W6 漏网清零 `design/engineering/code-conventions.md「2.5 玩家可见文案承载」禁在` | 静态断言 | player_copy_sweep_test::_sweep_zero_product_literals | 单元 | 闸跑批（读盘 grep） | 产品码三目录豁免词法外中文字面量=0 | 新增：文案漏网清零 | + +测试方式两分法：W1–W4、W6 归调试接口验；场景文案渲染观感归用户目检（登记不阻塞）。 +测试削弱申报：无删旧断言；display_name 空串校验改 key 格式校验＝判据收紧非放宽。 +独立验收审计：reports/iter-验收审计-<日期>.md；高档全量审计。 + +## 9. 异常分级 + +L1 自救：key 命名撞键时按模板加域段重排（登记 strings.csv 一次性变更）。L2 记录继续：单张表 key 迁移的进度性闸红（修复继续）。L3 停机呈报：表行 key 化发现 schema 外消费面（代码直读中文值比对）＝停卡呈报；机检预算互斥＝上游缺陷停卡退回写卡段；tr() 取不到 key（返回 key 本身）出现在真实入口＝L3（fail-fast 精神：呈现面露 key 即缺陷，禁静默兜底字典）。 + +## 10. 代拍板白名单 + +key 命名的域段用词（模板内）；strings.csv 行排序（按域分组）；探路 key 的具体文案值；tr 取回后格式化的空参防御写法（不改变判据）。 + +## 11. 待裁点 + +零待裁点，开工门=U0。（承载形态 CSV/tr 单点已由 code-conventions §2.5 用户裁锁定；key 模板属实现细节，经第 3 节契约钉死。） + +## 12. 落位与可复用性预检 + +- strings.csv＝新增：Godot 原生翻译承载，盘上无同件（grep l10n/translation 零命中）；落点唯一 game/data/l10n/。 +- **测试件复用面**：字面量扫描与 tr 往返断言**扩展在册 `player_copy_sweep_test.gd`**（同职责承载——README「玩家面文案」/「刷新提示文案读表拼接」两行已用该件做源扫描），不新增 strings_single_source_test.gd；表行 key 格式断言新增 `config_table_key_test.gd`（数据面校验与呈现扫描职责不同，不可并入 player_copy_sweep——单一变化原因不同）。 +- 翻译注册＝引擎原生（Project Settings→`internationalization/locale/translations`），零自建加载代码；不复用/不自建 Dictionary 文案表（违反 §2.5 单点——用引擎原生 tr）。 +- SOURCE_NAMES 常量改 tr 后删除原 Dictionary——无别名残留。 +- 分层交互：core 只发 key（设计契约）；取文案全部在 Node 语境 tr()（presentation/views）；无 Core→翻译服务依赖。 + +## 13. 禁为机检文本保留无效成员 + +禁为迎合静态断言保留 display_name 旧键、空壳 getter、别名映射；schema 改名后旧键出现即 L3（第 9 节）。 + +## 14. 实现规范预算 + +新增测试文件一件：config_table_key_test.gd（三查：公开方法 1 个测试入口＋少量 helper ≤20、成员 ≤15、分支 ≤8——单断言件远低于阈值）。扩展件 player_copy_sweep_test.gd 净增 3 个函数（现公开面远低于 20，S13 键预期只降不升）。无新增生产文件（strings.csv 为数据件）。存量触面：grant_segment 等四件为删改拼装行（函数分支数只降不升）；十 schema 校验行数持平；T0 申报 S13 键只降不升。无迁移函数（拼装行就地改值，不跨文件迁移）。 + +## 15. 拆分边界纪律 + +本卡新增单元两件：①player_copy_sweep 扩展三函数——职责语句＝「呈现面文案承载的扫描断言（tr 往返/toast 字面量/产品码漏网）」；单一变化原因＝文案承载规则；集体身份＝既有 PlayerCopySweep 套件扩展。②config_table_key_test——职责语句＝「数据表行文案 key 的格式与旧键清零断言」；单一变化原因＝表行 key 化契约；集体身份＝ConfigTableKey 套件。表行 key 化为等值替换非拆分；无凑计数袋形态。判据权威＝code-conventions §1.1。 + +## 16. 复核记录 + +| 轮次 | 复核者身份 | 发现 | 去向 | 处置结果 | +|---|---|---|---|---| +| 1 | 只读子代理（Explore，未参与撰写） | B1 对照表 W1–W6 需求点格全缺判据出处锚 | 补写 | 六行锚补齐（锚目标句经复核者实读全命中：code-conventions §2.5、战斗结算 v2.1 :87、术语表 v1.30） | +| 1 | 同上 | B2 对象级失实：game/ 22 个 .tscn 中文字符实为 0（卡写 70 行静态文案），T4/W5 验收对象不存在 | 补写 | 现状事实改「复核实证=0」；T4 场景 key 化删除、W5 重定为核验行（.tscn 面纳入 W6 扫描词法防回归）；动态装配中文归 W4 面（B6 清单）；估时重算 | +| 1 | 同上 | B3 W1 判据缺 locale 前提：默认 locale=en，tr() 按 key 原样返回，默认态必红 | 补写 | T0 补 locale 设定步（internationalization/locale/fallback 或测试端 set_locale）；设置键名一并修正 | +| 1 | 同上 | B4 schema 面少报：「display_name 空」校验实为 12 处/10 件（卡写 7 处），W2 旧键 grep=0 会漏件打红 | 补写 | 现状事实/结构图/T1 改十件全集；W2 判据改「十件全集」 | +| 1 | 同上 | B5 新增 strings_single_source_test.gd 与在册 player_copy_sweep_test 同职责，预检未回答为何不扩展 | 补写 | 改为扩展 player_copy_sweep_test 三函数；表行 key 断言独立成 config_table_key_test（职责不同）；§12/§14/结构图同步 | +| 1 | 同上 | B6 残余文案清单漏项：node_overlay 三处＋main_adventure_flow 终局字串四处 | 补写 | §2 清单补 7 处（合计 33 处级）；T3 范围并入 | +| 1 | 同上 | B7 能力行未入 README 表 | 补写 | README 增「文案承载单点/表行文案 key 化/文案漏网清零」三行（写卡段当场入表） | +| 1 | 同上 | B8 引擎面两处：设置键实名 internationalization/locale/translations；auto_translate 4.3 起弃用（4.7 现行=auto_translate_mode） | 自判 | T0 键名改正；auto_translate 提法随 T4 删除（B2）一并消解 | +| 1 | 同上 | B9 估时加总与卡面不符 | 自判 | 合计改 3.5–5.25 日（中值 4.375，随 B2 重算） | +| 2 | 只读子代理（Explore，确认轮，未参与撰写与处置） | N1 卡A 删件断编译面仍漏 5 处（player_copy_sweep_test:59/:110-112、stage_background_test:194-201、theme_projection_test 三处、feat_vouchers_test:294-296、battle_orchestrator.gd:19 注释） | 补写 | 卡A §2 现状、结构图、T1 三处补登等价改写义务（含 log_band 几何断言退役） | +| 2 | 同上 | N2 卡B「合计 33 处级」与自身明细（37）矛盾，实际约 43 处级 | 补写 | §2 与 T3 计数改「约 43 处级」，清单以 §2 为唯一依据 | +| 2 | 同上 | N3 终局字串与 battle_end 行锚错位（:113/:114/:181、:230/:231） | 自判 | 行号逐处改正 | +| 2 | 同上 | N4 W4/W6 域内实测漏项（main.gd:367/374/378/381/453/497/502、main_adventure_flow:116/231/233/241、curio:79/137） | 补写 | §2 清单补 13 处；T3 以 §2 为唯一依据 | +| 2 | 同上 | N5 跨卡漏项：Narrator.phase_text 阶段指示文案组（hud_presenter.gd:344）——卡A 直连后落地所在未入卡B 迁移清单 | 补写 | 卡A T1 补直连义务注记；卡B §2/T3 补该组 | +| 2 | 同上 | N6 键集面不全：feat_table:16、meta_tree_table:17 两处无人认领；hero_table:23 校验漏计（13 处/11 件） | 补写 | §2/T1/结构图改十一件＋键集同步面五处 | +| 2 | 同上 | N7 卡A T1 锚「battle.md 组件表『终局判定文案』」悬空（实际在 README:168） | 自判 | 改指 game/tests/README.md 能力行 | +| 2 | 同上 | N8 卡A §14「新增函数两处」实为一处 | 自判 | 改「一处」 | +| 2 | 同上 | N9 行号/编号 drift：battle.md:194→:195、main.gd:420→:421、ks :403→:404、卡B T0「T3 闸用」→T4 | 自判 | 逐处改正 | + +引擎技术面三查（同轮）：tr/TranslationServer 回退行为、Tween、Label 描边在 4.7 存在且行为如卡——B3/B8 已按引擎事实落卡，无未判发现。 + +## 17. 复核自审七查执行记录 + +①规格覆盖：目标 6 项→T0–T4 与 W1–W6 逐条对上；②步骤扫描：key 模板/豁免词法/断言形态全钉死，无 TBD；③类型一致性：STRINGS_CSV_PATH（T0 定义，T4 取用）、DISPLAY_KEY_*（T2 产出）；④审查焦点：tr 取不到 key 的失败形态→W1 断言含返回值比对＋L3 申报；.tscn 面零中文实证→W5 核验行＋W6 扫描词法防回归；⑤篇幅：无函数体；⑥落位复用：见第 12 节（含测试件复用面）；⑦预算：见第 14 节。 diff --git a/reports/需求卡片-明细带退役呈现改版批-2026-11-10.md b/reports/需求卡片-明细带退役呈现改版批-2026-11-10.md new file mode 100644 index 00000000..f236d5ee --- /dev/null +++ b/reports/需求卡片-明细带退役呈现改版批-2026-11-10.md @@ -0,0 +1,170 @@ +# 需求卡片：明细带退役呈现改版批 + +- 来源：待办清单「B 区明细带退役＋即时反馈画面化」（2026-11-10 登记，来源=会话提及）（唯一事实源：design/ux/battle.md 2026-11-10 版「即时反馈画面化预览」节＋组件表 B 区明细带行＋design/gdd/systems/战斗循环/敌人系统.md v2.2「半血解锁呈现规格」） +- 验收档：中（后果玩家可见、不损持久状态；golden 基线换代走审核关卡） +- 设计前置：三屏预览 2026-11-10 用户人审通过（battle.md 内嵌 SVG＋像素判据句）；三裁记录＝带整条退役／叙述行六类全砍／清图与解锁 toast 改画面，均为用户当轮裁决 + +## 1. 目标与完成定义 + +B 区明细带（battle_log_view）整条退役：组件、挂载、六类冒险叙述行、结算明细回看遗留件全删；清图兑付浮字实装（替代「清图奖励：××」toast）；Boss 解锁拍零新增呈现（删 row_pacer 解锁技名 toast）；探针与测试锚等价改写；渲染基线换代并过用户审核。完成定义＝本卡对照表 V1–V7 全绿＋基线过审＋代码域闸绿。 + +## 2. 现状事实（file:line 实查） + +- `game/presentation/views/battle_log_view.gd`（全件 70 行，实测）：明细带壳——挖掘期摘要位（`_summary`，battle_log_view.gd:62 仅 clear、全库无写入点＝恒空）＋结算期叙述行 RichTextLabel（`_log.visible = settle`，battle_log_view.gd:69）＋提示字「上轮摘要（回看归「生涯」）」（:56）。 +- 引用面 10 文件：main_ui_build.gd:45（装配）、scenes/adventure_screen.gd:12-13（壳声明）、ui_battle.gd、ui_assembler.gd、battle_stage_view.gd、hud_presenter.gd、main.gd、main_adventure_flow.gd、main_debug_flow.gd、views/ui_kit.gd:484（注释）。 +- 叙述行写入点：main_adventure_flow.gd:36（关卡开场）/65（节点横幅）/70（奖励）/75（恢复）/88（商店）/170（岔路）、main_debug_flow.gd:90（调试开场）。Narrator 其余消费点（删件断编译面，全数登记）：main_adventure_flow.gd:109（adventure_summary_text）/111（keystone_settle_text）/179（battle_end_text）喂 end_overlay、main.gd:373/377/380（battle_end_text 开浮层）、hud_presenter.gd:344（phase_text——阶段指示文案，随带退役改组合根直拼或删除）、curio_interact_controller.gd（10 处 `Narrator.` 调用）、curio_pick_overlay.gd（仅 ：3/:90 注释引用，零代码消费——删注释即可）。 +- 删件测试断编译面（load/实例化 battle_narrator 与 battle_log_view 的测试件，等价改写义务全数登记）：tests/unit/presentation/player_copy_sweep_test.gd:59（load battle_narrator）/:110-112（load battle_log_view 并走方法表）、stage_background_test.gd:194-201（实例化 log_view＋log_band 几何断言）、theme_projection_test.gd:46/:385（_smoke_battle_log_view）/:473-480（Narrator.level_open_line 断言）、tests/unit/core/feat_vouchers_test.gd:294-296（load battle_log_view）；core/battle_orchestrator.gd:19（注释提 battle_log_view._format_row——注释同步删）。 +- 清图 toast：main.gd:420 `show_toast("清图奖励：%s"…)`；Boss 解锁技名 toast：row_pacer.gd:94 `show_toast(String(row.get("display_name","")))`。 +- 结算明细回看：views/settlement_review_overlay.gd 全件零调用（唯一引用=ui_kit.gd:484 注释）。 +- 布局字段：battle_layout_table.gd:11-25（`log_band_h_dig`/`log_band_h_settle` 定义＋域校验）；游戏视图经 battle_log_view._init 读取（layout.log_band_h_dig，battle_log_view.gd:18）。 +- parsed_text/叙述行消费：probe/ui_probe.gd:113（等「节点 1/」）、probe/ui_click_probe.gd:624/684/1119/1152/1569（等「· 种子」叙述行出现）、tests/unit/presentation/battle_log_zero_text_test.gd:80-90（B 区零新增行断言）。 +- 恢复点一手呈现：views/node_overlay.gd:26 `show_rest(healed, hp_after, max_hp)`（main_adventure_flow.gd:74 调用）——B 区 rest_line 纯重复。 +- 渲染基线：game/tests/golden/battle_screen.png、board_L1_dungeon.png、board_L2_underdark.png、board_L3_deep_underdark.png（明细带在画者受影响）。 + +## 3. 设计契约 + +- 🔴 B 区零文字带：明细带退役后禁任何新文字条、日志壳、摘要位（battle.md「即时反馈画面化预览」节）。 +- 🔴 Boss 解锁拍零新增呈现：解锁拍 B 区新增可见元素数 = 0；告知仅由既有意图徽标承载（敌人系统 v2.2）。 +- 🔴 兑付浮字全程不遮棋盘：浮字底缘恒在棋盘上缘上方 ≥6px；无标题、无底牌（battle.md 像素判据）。 +- 🔴 结算 9 类行协议不动：数据面流水照记，display 字段值形态变更归文案入表卡，本卡禁碰。 +- 🔴 禁变异测试与撤销取证：解锁「零新增」断言用逐元素快照比对（真实入口进入），禁人为注入解锁再回退比对。 + +## 4. 范围边界 + +做：上列退役与浮字实装、探针/测试锚等价改写、能力表同批维护、golden 受影响图换代呈审。 +不做（去向）：文案 key 化与 strings.csv（文案入表卡，紧随本卡；本卡新引入的浮字文案暂以呈现层字串承载，登记进该卡范围）；`log_band_h_*` 表字段与 schema 删除（工具批，battle.md:118 已注明「字段删除归工具批」）；生涯界面（在册概念）；settlement_summary.md 等 ux 文档若涉叙述行提法的修订（实现批产出反哺点清单）。 + +## 5. 关联文档同步面 + +| 文档 | 关联点 | 同步义务 | +|---|---|---| +| design/ux/settlement-summary.md | 若含结算叙述行/摘要提法 | 实现批列反哺点，用户裁决后文档批落文 | +| 体验验证清单.md | 逐行目检类条目在带退役后失锚 | 实现批列反哺点 | +| roadmap.md | 本批入迭代后行状态 | 编排段义务，非实现批 | +| design/gdd/systems/战斗循环/战斗表现.md | 若引用叙述行承载位 | 实现批列反哺点 | + +## 6. 卡前·文件结构图 + +| 文件 | 职责 | 行为改动 | +|---|---|---| +| game/presentation/views/battle_log_view.gd | 删除（明细带壳全件） | 是（V1/V5） | +| game/presentation/views/settlement_review_overlay.gd | 删除（遗留件报废） | 否（零调用，V1 树断言覆盖） | +| game/presentation/battle_narrator.gd | 删除（六类叙述行生成器；phase_text/结算提示的消费点改直连或删除） | 是（V5） | +| game/presentation/main_adventure_flow.gd | 删六处 append_bb；恢复/商店节点反馈已有弹窗浮层无需补 | 是（V5） | +| game/presentation/main_debug_flow.gd | 删调试开场叙述行 | 是（V5） | +| game/presentation/main_ui_build.gd、scenes/adventure_screen.gd、ui_battle.gd、ui_assembler.gd、battle_stage_view.gd、hud_presenter.gd、views/ui_kit.gd | 摘除 log_view 壳与引用 | 是（V1） | +| game/presentation/main.gd | 清图 toast 改兑付浮字装配；删 Narrator 常量与消费 | 是（V2/V3） | +| game/presentation/views/board_zone_view.gd | 新增兑付浮字层（spawn_clear_reward_text） | 是（V2/V3） | +| game/presentation/row_pacer.gd | 删解锁技名 toast（row_pacer.gd:91-94） | 是（V4） | +| game/presentation/views/curio_pick_overlay.gd（仅注释）、curio_interact_controller.gd（10 处） | Narrator 引用删净/消费点改写 | 是（V5） | +| game/tests/unit/presentation/battle_narrator_test.gd | 删除（被测对象退役） | 是（V5） | +| game/tests/unit/presentation/player_copy_sweep_test.gd、stage_background_test.gd、theme_projection_test.gd、tests/unit/core/feat_vouchers_test.gd | 删件断编译面等价改写（load/实例化/断言改写，§2 清单五处）＋stage_background 的 log_band 几何断言退役 | 是（V1/V5） | +| game/core/battle_orchestrator.gd:19 | 注释提 battle_log_view._format_row——删注 | 否 | +| game/tests/unit/presentation/clear_reward_text_test.gd、log_band_retired_test.gd、unlock_zero_ui_test.gd | 新增（V2/V3、V1/V5、V4） | 是 | +| game/probe/ui_probe.gd、ui_click_probe.gd | 等锚改写（叙述行锚→棋盘/意图锚） | 是（V7） | +| game/tests/unit/presentation/battle_log_zero_text_test.gd | 删除（被测对象退役）＋新增明细带退役断言归属测试 | 是（V1） | +| game/tests/README.md | 能力行同批维护（本卡写卡段执行，非实现批） | 否 | +| game/tests/golden/battle_screen.png、board_L3_deep_underdark.png | 基线换代（逐张呈用户审核） | 是（V6） | + +## 7. 任务卡 + +### T0 锚普查与基线预读（0.25–0.5 日） +- [ ] 实跑 `ui_probe`/`ui_click_probe` 与渲染闸，记录改前读数（S13 键与基线图清单） +- [ ] 逐处登记 parsed_text/叙述行锚的替位锚（等价语义：进战斗=棋盘 install 可见 / 换层信号），写进本卡附录不改码 +- [ ] S13 预期申报：删除件键清零、touch 面只降不升 + +### T1 明细带与叙述行退役（1–1.5 日） +- [ ] 删 battle_log_view.gd、settlement_review_overlay.gd、battle_narrator.gd、battle_narrator_test.gd 四件（测试件随被测对象退役，语义由 log_band_retired_test 承接） +- [ ] 摘除 6.结构图所列壳与引用（adventure_screen 壳声明、ui_battle/ui_assembler 装配、hud_presenter phase_text 消费改组合根直拼或删除、curio_interact_controller 十处消费点改写、curio_pick_overlay 两处注释删净）＋终局消费点改写：main_adventure_flow.gd:109/111/179 与 main.gd:373/377/380（battle_end_text 退役，verdict_line/摘要串由组合根按 battle_result 与 runner 读数直拼——能力锚=game/tests/README.md「终局判定文案与战末账行」行） +- [ ] 测试断编译面等价改写（§2 清单五处）：player_copy_sweep_test/stage_background_test/theme_projection_test/feat_vouchers_test 的 load 与断言改写（log_band 几何断言退役）；battle_orchestrator.gd:19 删注 +- [ ] main_adventure_flow.gd 删六处 append_bb；main_debug_flow.gd 删调试叙述行 +- [ ] row_pacer.gd 删解锁技名 toast（skill_unlock 行呈现侧不再消费 display_name） +- [ ] 接口产出：无（纯删改）；验证：单元＋冒烟 exit 0 + +### T2 清图兑付浮字（0.5–1 日） +- [ ] board_zone_view.gd 新增 `func spawn_clear_reward_text(text: String) -> void`：单行 Label（字高 17px、暖白 #F5EAD0、2px 深墨描边、微金光晕），自棋盘中央上方起、2.5s 内**上浮约 40px**（位移量，非起始定位——battle.md:195）并渐隐（Tween，尊重减动效开关→直达终态） +- [ ] main.gd 清图 handler（:421 show_toast）：`show_toast("清图奖励：%s"…)` 替换为 `board_zone.spawn_clear_reward_text(兑付值)`——兑付值取现行 toast 同源（row.get("display") 清洗后内容），暂以呈现层字串承载（文案入表卡收编）；**零兑付守卫保留**（:420 `type != "reward_ineffective"`——未生效行不弹浮字，安静留数据面，语义重述随明细带退役） +- [ ] 验收步骤：V2/V3 断言（见对照表）落 tests/unit/presentation/clear_reward_text_test.gd +- [ ] 接口取用：无；产出：`spawn_clear_reward_text(text: String)`（T3 探针取用） + +### T3 测试与探针锚改写（0.5–1 日） +- [ ] 删 battle_log_zero_text_test.gd 与 battle_narrator_test.gd；新增 tests/unit/presentation/log_band_retired_test.gd：adventure_screen 实例树内无 log_view/settlement_review 节点（V1）；B 区子树零 RichTextLabel 文字节点（V5） +- [ ] 解锁零新增断言：tests/unit/presentation/unlock_zero_ui_test.gd——解锁触发前后 B 区子树逐元素快照比对，新增数=0（V4） +- [ ] ui_probe.gd:113、ui_click_probe.gd 五处等锚改写（替位锚按 T0 附录） +- [ ] 能力行落名：见对照表能力列 +- [ ] 验证：单元全套件＋两探针 exit 0 + +### T4 基线换代与收口（0.5 日） +- [ ] 渲染闸重截受影响图（battle_screen、board_L3；board_L1/L2 若带在画一并），**逐张呈用户审核后才入库**（触发基线审核关卡） +- [ ] 产出物落位卡：reports/iter-实现报告（实机目检清单：浮字观感/解锁拍/挖掘结算两态布局）、reports/iter-反哺点清单（同步面 4 行逐条给落点） + +估时合计：2.75–4.5 日（中值 3.625）。 + +## 8. 验证闸（改动—验收对照表） + +| 需求点 | 改动（文件:行为） | 验收测试 | 层级 | 真实入口 | 判据绑定面 | 能力行 | +|---|---|---|---|---|---|---| +| V1 明细带退役 `design/ux/battle.md「Component Inventory」明细带整条退役` | battle_log_view/settlement_review 删除＋壳摘除 | log_band_retired_test::test_no_log_view_node | 单元 | adventure_screen 场景实例化 | 场景树节点名集合（无 log_view/settlement_review） | 新增：B 区零文字带 | +| V2 兑付浮字呈现 `design/ux/battle.md「即时反馈画面化预览」清图兑付浮字` | board_zone_view.spawn_clear_reward_text＋main.gd 装配 | clear_reward_text_test::test_spawn_and_decay | 单元 | 清图完成信号（round_end clear 分支） | 浮字节点文本=兑付值＋2.5s 后 freeing | 新增：清图兑付浮字 | +| V3 浮字不遮棋盘 `design/ux/battle.md「即时反馈画面化预览」浮字全程不与棋盘格面重叠` | 同上 | clear_reward_text_test::test_no_overlap＋test_decay_curves | 单元 | 同上 | 四判据全绑：rect 相交=空；底缘距棋盘上缘 ≥6px；渐隐 alpha 帧间步进 ≤0.1；兑付值可读时长 ≥60% 生命期 | 新增：清图兑付浮字 | +| V4 解锁拍零新增 `design/gdd/systems/战斗循环/敌人系统.md「目标顺位与意图线索」解锁拍零新增呈现` | row_pacer.gd 删 toast | unlock_zero_ui_test::test_zero_delta | 单元 | skill_unlock 高光行经 row_pacer 的真实消费流（固定种子令 Boss 半血后摇中闩技；快照取在 row_pacer 消费时刻，非阈值事件发射位） | B 区子树逐元素快照差=0（绑消费点提交面，防发射位空转假绿） | 新增：解锁拍零新增呈现 | +| V5 叙述行全砍 `design/ux/battle.md「Component Inventory」冒险叙述行六类随带全砍` | battle_narrator 删＋消费点摘除（main_adventure_flow 六处＋main_adventure_flow:109/111/179 终局三处＋main.gd:373/377/380＋curio 十处＋debug_flow 一处） | log_band_retired_test::test_b_zone_zero_text | 单元 | 节点推进/恢复/商店/终局真实流 | B 区零文字节点＋battle_narrator 符号 grep=0 | 新增：B 区零文字带 | +| V6 基线换代 `design/ux/battle.md「即时反馈画面化预览」战斗屏纵向` | golden 受影响图重截 | 渲染闸 golden 比对 | 探针 | 渲染闸跑批 | 逐像素；**触发基线审核关卡**（T4 呈审） | 既有：战斗屏三区几何与棋盘格边长（分辨率两档×四档板型） | +| V7 探针锚等价 `design/ux/battle.md「Component Inventory」结算明细带（已退役）` | ui_probe/ui_click_probe 五处 | 两探针跑批 exit 0 | 探针 | 真实 UI 驱动流 | 锚语义等价（进战斗/换层——叙述行锚失据即换） | 既有：停点链与控件级真输入命中 | + +测试方式两分法：V1–V5、V7 归调试接口验；浮字观感、解锁拍目感、两态布局归用户目检（登记不阻塞，写入实现报告实机目检清单）。 +测试削弱申报：battle_log_zero_text_test.gd 与 battle_narrator_test.gd 删除（被测对象退役，语义由 log_band_retired_test 承接；game/tests/README.md「战斗叙述与终局文案」能力行同批退役改写为「终局判定文案与战末账行」——已入表）；无阈值放宽。 +独立验收审计：reports/iter-验收审计-<日期>.md，入口=本对照表全量；未过禁合并。 + +## 9. 异常分级 + +L1 自救：探针锚替位的一次重试、Tween 参数微调。L2 记录继续：golden 图因既有环境色差微漂（容差内）。L3 停机呈报：基线审核被用户否决（回 T2 调观感）；机检预算互斥＝上游缺陷停卡退回写卡段；删除件发现隐藏消费面（grep 外的运行期引用）＝停机呈报，禁就地续删。 + +## 10. 代拍板白名单 + +浮字缓动曲线与光晕参数微调（判据内）；探针等锚的具体替位信号选择（语义等价前提）；测试私有 helper 命名；叙述行删除时的连带死代码清理（同文件内）。 + +## 11. 待裁点 + +零待裁点，开工门=U0。（三裁——带退役/叙述行全砍/toast 画面化——已于设计段由用户裁决；浮字落点经落位预检自判见第 12 节。） + +## 12. 落位与可复用性预检 + +- 浮字层＝**新增**（board_zone_view 内私有层）：不能复用浮空数字层——该层按格锚定、随棋盘滚动/换图重建，兑付浮字需整板锚定且横跨换图时序，语义不同；落点唯一（board_zone_view，棋盘容器的既有宿主）；grep `spawn_.*text\|float_text` 盘上无同义件。 +- 删除件三件（battle_log_view/settlement_review_overlay/battle_narrator）：无复用面，引用面已全数列入结构图。 +- 恢复/商店反馈复用在役 node_overlay.show_rest（node_overlay.gd:26）与 shop_overlay——零新增。 +- 分层交互：浮字层只读清图信号载荷（组合根装配传入），不触 Core；经 board_zone 既有出口，禁绕 HUD 框架直建 CanvasLayer。 + +## 13. 禁为机检文本保留无效成员 + +本卡为退役＋小新增卡：删除件不留空壳、别名、转发函数；S13 键与删除件相关的登记值预期清零，机检键与本卡契约互斥时实现段停卡呈报，禁自造第三条路。 + +## 14. 实现规范预算 + +新增测试文件三件（三查：公开方法 ≤20／成员 ≤15——三件均为单套件测试件，各 1 个测试入口函数＋少量 helper，分支 ≤8，远低于阈值）：clear_reward_text_test.gd、log_band_retired_test.gd、unlock_zero_ui_test.gd。无新增生产文件。新增函数一处：board_zone_view.gd `spawn_clear_reward_text`（+1 公开方法，该文件现公开方法数远低于 20；成员 +2：浮字层引用、Tween 引用）；main.gd 净增 0（toast 装配改浮字装配，同类替换）。迁移对账：battle_narrator 无函数迁入他件（全删）；main_adventure_flow/main.gd 的 verdict 装配为就地改写非迁移。存量触面：T0 申报 S13 键只降不升。 + +## 15. 拆分边界纪律 + +本卡拆出单元仅浮字层一处：职责语句＝「清图兑付的整板锚定浮字层（生成、上浮渐隐、减动效直达）」；单一变化原因＝兑付呈现观感；集体身份＝ClearRewardText 层。无凑计数袋形态；按纪律拆不出内聚单元的情形不适用（零重构拆分）。判据权威＝code-conventions §1.1。 + +## 16. 复核记录 + +| 轮次 | 复核者身份 | 发现 | 去向 | 处置结果 | +|---|---|---|---|---| +| 1 | 只读子代理（Explore，未参与撰写） | A1 对照表 V1–V7 需求点格全缺判据出处锚 | 补写 | 七行锚补齐（锚目标句经复核者实读全命中：battle.md「即时反馈画面化预览」/「Component Inventory」、敌人系统 v2.2「半血解锁呈现规格」） | +| 1 | 同上 | A2 T2 把锚句「上浮约 40px」位移量误读为起始定位量 | 补写 | T2 改「自棋盘中央上方起、2.5s 内上浮约 40px（位移量）」（battle.md:194 依据随行） | +| 1 | 同上 | A3 V3 只绑 rect 相交，缺节内另三条像素判据 | 补写 | V3 判据绑定面扩为四判据（相交空/≥6px/alpha 步进 ≤0.1/≥60% 可读），加 test_decay_curves 用例 | +| 1 | 同上 | A4 V4 真实入口=阈值事件发射位（round_cycle.gd:121），快照恒 0＝空转假绿；toast 可观测提交位=row_pacer 消费时刻（row_pacer.gd:93-94） | 补写 | V4 入口钉 skill_unlock 行真实消费流＋固定种子取径＋快照取消费时刻 | +| 1 | 同上 | A5 删 battle_narrator 断编译消费点漏登记（main_adventure_flow:109/111/179、main.gd:373/377/380、curio 十处、curio_pick_overlay 仅注释） | 补写 | 现状事实、结构图、T1 三处补全（含 verdict_line 组合根直拼去路） | +| 1 | 同上 | A6 battle_narrator_test.gd 未列删除面；README:168「战斗叙述与终局文案」能力行随删失效 | 补写 | 结构图/T1/测试削弱申报补四件删除；能力行同批改写（已在 game/tests/README.md 入表） | +| 1 | 同上 | A7 预算节「无新增文件」与 T2/T3 三个新增测试件矛盾 | 补写 | 预算节补三件三查；结构图补测试件行 | +| 1 | 同上 | A8 能力列写层名非能力名，且新增能力未入 README 表 | 补写 | 能力列改能力名；README 增「B 区零文字带/清图兑付浮字/解锁拍零新增呈现」三行（写卡段当场入表） | +| 1 | 同上 | A9 battle_log_view.gd 实测 70 行（卡写约 110）；curio_pick_overlay 仅注释引用 | 自判 | 两数/表述就地改正（wc -l 实测依据） | +| 1 | 同上 | A10 估时加总实为 2.75–4.5 | 自判 | 合计改 2.75–4.5 日（中值 3.625） | +| 1 | 同上 | A11 零兑付守卫（main.gd:418-420）去留未钉 | 补写 | T2 补守卫保留句（未生效行不弹浮字，语义重述随带退役） | + +引擎技术面三查（同轮）：Tween/Label 描边/减动效直达在 4.7 存在且行为如卡；UI 移动走 Tween 合 NEVER-9；Gotcha-3（Tween 随节点消亡）由 board_zone_view 常驻宿主承载——无发现。 + +## 17. 复核自审七查执行记录 + +①规格覆盖：目标 4 项→T1–T4 与 V1–V7 逐条对上；②步骤扫描：无 TBD/酌情，函数体未预写；③类型一致性：`spawn_clear_reward_text(text: String)` 单点定义 T2、取用 T3；④审查焦点：换图时序与浮字生命周期竞争（清图后即刻 install）→V2 断言含 decay 完成前置；减动效开启→T2 步骤内含直达终态分支；⑤篇幅：无函数体代码块；⑥落位复用：见第 12 节；⑦预算：见第 14 节。 diff --git a/待办清单.md b/待办清单.md index 8be31467..0a03bfc1 100644 --- a/待办清单.md +++ b/待办清单.md @@ -67,9 +67,9 @@ #### 结算明细文案入表（2026-11-07 登记，来源=批次移交） -**实况**：玩家可见文案承载换代设计闭合——承载规则=code-conventions.md §2.5（文案 key 单点、文案值住 data/l10n/strings.csv）；同步修订 design/gdd/systems/表现与支撑/设置与本地化.md v1.3、战斗循环/战斗结算.md v2.1（:87 条款）、战斗循环/增益状态.md v1.8、战斗循环/敌人系统.md v2.0、跨局循环/锻造工坊.md v0.14、跨局循环/秘宝.md v1.5、术语表.md v1.30（文案 key 词条）；字段更名 display_key／desc_key。 +**实况**：玩家可见文案承载换代设计闭合——承载规则=code-conventions.md §2.5（文案 key 单点、文案值住 data/l10n/strings.csv）；同步修订 design/gdd/systems/表现与支撑/设置与本地化.md v1.3、战斗循环/战斗结算.md v2.1（:87 条款）、战斗循环/增益状态.md v1.8、战斗循环/敌人系统.md v2.0、跨局循环/锻造工坊.md v0.14、跨局循环/秘宝.md v1.5、术语表.md v1.30（文案 key 词条）；字段更名 display_key／desc_key。已写卡 reports/需求卡片-文案入表批-2026-11-10.md **改动面**：文档＋游戏代码 -**状态**：文档设计已闭合＋待写卡 +**状态**：文档设计已闭合＋已写卡 #### UI 贴图重构批——元进度件仍是程序化占位（2026-10-13 登记，来源=审计发现） @@ -81,6 +81,12 @@ **状态**：待美术设计（备选） +#### B 区明细带退役＋即时反馈画面化（2026-11-10 登记，来源=会话提及） + +**实况**：设计闭合——[battle.md](design/ux/battle.md)（2026-11-10 版）「即时反馈画面化预览」节（明细带整条退役＋清图兑付浮字＋Boss 解锁拍零新增呈现，内嵌 SVG＋像素判据，三屏预览 2026-11-10 用户人审通过）；[敌人系统](design/gdd/systems/战斗循环/敌人系统.md) v2.2（解锁拍零新增呈现，一次性技能名 toast 退役）；[HUD框架](design/gdd/systems/表现与支撑/HUD框架.md)（明细带提法清零，回看覆盖层同批报废）。叙述行六类随带全砍（分流裁决见 battle.md 组件表 B 区明细带行）。已写卡 reports/需求卡片-明细带退役呈现改版批-2026-11-10.md +**改动面**：游戏代码 +**状态**：文档设计已闭合＋已写卡 + #### 扩展节点类型——危险/精英节点与特殊地形节点（2026-10-21 登记，来源=会话提及） **实况**：用户定方向：Alpha 版只留现行四类（战斗/奖励/恢复/商店），以下两类留到以后再做——①危险/精英节点（怪物与普通战斗不同、奖励肥）；②特殊地形节点（效果修饰：地图战斗资源、敌我伤害、金币比例等）。内容未设计。