DKChan
430419cf01
用户拍板 2026-10-05。命名理由：「魔法」一词在本作已被征用为敌方侧 伤害/护甲语汇（magic_bolt 魔法矢 / magic_recoil 魔法反噬 / magic 魔法族 格面微光 / ward 魔法护甲），「魔法道具」易被读成"魔法属性的道具"； 「秘宝」取"神秘·强大·稀有"义，与九件内容气质（工兵/工程/手艺向）契合， 且与局内道具（奇物）不冲突。**同调位机制名保留不变**（attunement 仍为 DND 词，机制血统不受更名影响）。 改动面（26 个文件，仅 design/ 目录）： - 正主重命名 systems/排雷循环/魔法道具.md → 秘宝.md，正文 17 处 + v0.9 版本行 - 称谓权威源 02-系统清单：文档树行 + 命名对照表 a5 行；英文代号 AUXILIARY_ITEMS 沿用不变（代码标识符口径，另批对齐） - registry/entities.yaml 30 处（referenced_by 九处 / owner 路径三处 / 存档域注释 / 承重规则段）；文件头新增 2026-10-05 注记并还原 2026-09-16 段旧名原文 - GDD 现行文档 16 个 + 美术 2 个 + 架构 1 个 - 历史定稿加名称已变更横幅（正文不改）：同调提案底稿（现行形态设计权威）、 同调实施批任务书 - 修复 research 内 2 处指向旧文件名的活链接（历史文档不改称谓但链接须可达） 刻意保留旧名：8 处版本历史行 + 自造短语全量清单 16 处（出口即删的 中间审计底稿，改称谓会令统计失真）。 代码层零改动（用户明令），遗留欠债 4 项待可跑冒烟批次收口： 1. 代码标识符仍为 aux_* / AUXILIARY_ITEMS（auxiliary 词根为过渡形态遗留） 2. battle_narrator.gd:117-118 仍输出"魔法道具"，且与同文件 139 行 arch_names["magic"]="魔法" 同屏两义共现——"魔法道具"进入玩家视野的 唯一残余通道 3. bonus_interact_controller.gd:76 清空 toast 仍写"魔法道具" 4. Godot 类名与文件名（AuxItemTable 等）改需同步 .uid 与 .tscn 引用 校验：registry 键集合前后一致（214 键零丢失零新增，仅增 7 行注记）； 改动文件正文类零残留（残留 8 处全在版本历史/换名说明内）；owner 路径 全部可达；链接检查除 2 处既有欠债（architecture.md 的 ../../design/ 多一层， 改动前即存在）外零断链。 注：局内道具名「奇物」全仓 md 零命中，本批未碰，避免两个换名批纠缠。
13 KiB
13 KiB
UX Spec: 关卡结算屏（Level Clear）——提升三选一选择面
Status: v2 义务锁定版（2026-10-01 迭代 10 奖励重构批重写——三件套快照展示退役，改三选一选择交互；呈现形态随实装批定，视觉终稿以表现层样张为前置，见 P1/OQ4；本批渲染层验证冻结——目检清单随批交付、实机目检待用户批准） Author: user + ZCode（UX 文档欠账处置批；迭代 10 重写） Last Updated: 2026-10-01 Platform Target: PC (Steam)——Keyboard/Mouse 主，全部操作纯鼠标可完成（同 battle.md） Template: UX Spec 来源: battle.md OQ8 欠账处置（2026-09-27 用户拍板建档）+ 迭代 10 奖励重构批（2026-09-30 用户拍板案丙——三选一/部分回血/钥石挪转，计划书 m3-iter10-loop-plan-2026-09-30.md）
Purpose & Player Need
关卡结算屏是关卡收束时刻的清算与选择面：末节点 Boss 倒下、本关结束，玩家在这里看到这一关的账（部分回血的兑付反馈），然后从三个提升选项里挑一件带走——本作第一个选择型奖励面。
一句话目的：让「打穿了一关」的收束感落在一笔算得清的账上，并把「这关带我变强」变成玩家自己做的决定。
- 提升三选一承载局内成长的选择权：池六种加权抽三、点选一件兑付、另两件丢弃不可反悔
- 部分回血承载收束反馈：通关不再自动回满，回血量一眼可读（满血回 0 合法）
- 钥石增量不在本屏（迭代 10 起）：Boss 击杀进账时刻的钥石增量行已迁战斗总结结算（settlement-summary.md v1.1）——单一展示面原则，本屏不重复
若此屏缺失或难用：奖励选择沦为无声的自动发放（选择权缺失）；三选一停点不可中断则续玩丢选择。
现行载体与目标形态（重要边界）
本屏没有独立新屏：现行与 MVP 目标载体都是关卡收束时刻的覆盖层反馈（HUD框架 P1 行「相邻域屏完整屏形态：MVP 以覆盖层反馈承载」）。本 spec 锁义务与数据锚，不锁视觉形态；完整屏形态归 P1 实装批。
| 时刻 | 载体（目标形态，迭代 10 实装） | 呈现内容 |
|---|---|---|
| Boss 战胜利（非末关） | 战斗总结结算（settlement-summary.md）→ 确认后进本屏 | 战利品行含钥石增量行 → 本屏：部分回血反馈 + 三选一三卡 |
| 非末关通关（本屏默认态） | 中场覆盖层改三选一选择交互（_inter_overlay 位置复用） | 部分回血兑付行 + 三张提升选项卡（点选+确认+兑付反馈） |
| 末关通关 / 失败 / 放弃 | 冒险结算（复用战斗终局 overlay） | 冒险摘要五件事 + 钥石入账明细——相邻域（冒险终结面，非本屏职责） |
Navigation Position
战斗屏 ──胜利（末节点 Boss）──▶ 战斗总结结算（GP/钥石增量行）──确认──▶ 【关卡结算（level_clear）】
├─ 非末关：回血反馈 + 三选一点选兑付 → 下一关开始（→ 关卡画面选路）
└─ 末关通关：直通冒险结算（相邻域）→ 返回存档/营地
失败不经本屏（战斗屏失败分支直达冒险终结）。
- 上游屏：战斗总结结算（Boss 胜利确认——settlement-summary.md v1.1）
- 下游屏：关卡画面（下一关开始，选路枢纽——屏级 spec：level-map.md）；末关时改接冒险结算（相邻域屏）
Entry & Exit Points
| 方向 | 触发 | 携带语境 |
|---|---|---|
| 进入 | 战斗总结结算确认 → 关卡收束（先清库后宣布）→ 非末关兑付部分回血 → 三选一候选呈现（bonus_pick 信号） | 三候选（件 id + 名称 + 效果行值）；部分回血前后生命读数；GP 账本余额（跨关延续） |
| 离开 | 三选一确认兑付 → 继续钮（唯一出口） | 兑付反馈载荷 → 下一关开始 |
零自动推进（冒险结构 契约 4）：三选一呈现后必须玩家点选才兑付，确认前玩家不被推着走；重复兑付被拒。选择停点可中断：断点附随件扩「奖励选择态」，续玩回到本屏同一候选（不重抽）。
Information Hierarchy（义务锁定）
按 2026-09-26 信息归属两铁律（循环口径 + 单一展示面）过闸后的准入清单：
- 三张提升选项卡（第一注视点）：件名称 + 一行效果读数（值读冒险表）——选择型奖励的本体；已达次数上限的件不出现（剔牌库在先）；秘宝件直显掷定的具体道具（「秘宝 / 探巢摆钟 · 真视 3×3」——掷定前置，候选抽定时掷定具体道具，追加批二）
- 部分回血兑付行：回血量（前后生命读数，如「生命 34 → 42」）；满血回 0 时呈「生命已满」反馈而非 0 字样
- 兑付反馈（确认后）：选中件效果一行（如「攻击 +1」）+ 另两件已丢弃提示
- 同调位替换子交互（条件呈现）：选秘宝件且库存满位时——现有件 + 新件共 N+1 选 N 的子面板：每件「丢弃换新」钮 +「放弃新件」钮；终态恒 ≤ 同调位
禁入清单（两铁律推导）：战斗小循环数据（结算明细、状态效果——留在战斗屏）；GP（呈现位已拍板 = 战斗总结结算 + 关卡画面常驻）；钥石增量与累计（迭代 10 起归战斗总结结算增量行 + 冒险总结结算收束明细——本屏零钥石元素）；营地柜台全量；冒险摘要五件事（末关时由相邻域冒险结算屏承载）；已达上限件（不出现在候选）。
States & Variants
| State | Trigger | What Changes |
|---|---|---|
| 三选一选择态（默认） | 非末关通关，候选已抽定 | 三卡呈现（零自动推进）→ 点选 → 确认 → 兑付反馈 → 继续 |
| 同调位替换子态 | 点选秘宝件且库存满位 | 子面板 N+1 选 N；两路出口（丢旧收新 / 放弃新件）后回主态兑付 |
| 兑付反馈态 | 确认兑付后 | 选中件效果一行 + 丢弃提示 → 继续钮点亮 |
| 末关通关 | level_clear 且末关 | 直通冒险结算——不发三选一与回血（奖励只朝下一战生效）；本屏不出现 |
| Boss 入口语境 | 击杀 Boss（恒为本屏入口前置） | 入口演出归战斗屏；钥石增量行归战斗总结结算——本屏不另设 |
Interaction Map
| 组件 | 动作 | 输入 | 即时反馈 | 结果（经组合根） |
|---|---|---|---|---|
| 提升选项卡 ×3 | 点选（单选高亮） | 左键 | 选中卡高亮、确认钮点亮 | 选中态暂存（未确认可改选）；点选秘宝件遇满位 → 替换子面板 |
| 确认钮 | 兑付选中件 | 左键 | 兑付反馈（效果一行） | AdventureRunner 兑付恰一件（重复兑付被拒）；另两件丢弃不可反悔 |
| 继续钮 | 接受结算、推进 | 左键 | 按钮下压 | 下一关开始（AdventureRunner.continue_to_next_level——兑付后受理） |
| 替换子面板钮 ×N+1 | 丢旧收新 / 放弃新件 | 左键 | 子面板关闭 | 库存终态恒 ≤ 同调位；原三选一兑付继续 |
复用既有交互范式，零新增原语：三卡点选 = 奖励节点 choice_box 按钮数组同族（node_overlay.show_reward_items 先例）+ 选路覆盖层点选确认两段式（level_map_screen 先例）；覆盖层容器 = 中场确认覆盖层位置复用。
Data Requirements
| Data | Source System | Read / Write | Notes |
|---|---|---|---|
| 三候选（件 id/名称/效果行值） | 冒险结构 bonus_pick 信号（加权洗牌掷 3，reward_pick 封闭流） | Read | 载荷自包含、despawn 前捕获；同种子同三候选（可复放） |
| 部分回血读数（回血前后生命） | 冒险结构生命账本（clear_heal_pct 兑付） | Read | 满血回 0 合法态文案化 |
| 兑付反馈载荷 | 冒险结构 bonus_resolved 信号 | Read | 选中件 id + 生效值 |
| 同调位库存（现有件清单） | 秘宝库存（关卡域） | Read | 替换子态数据源；上限 = transitional_sync_slots（过渡键） |
| 冒险摘要（五件事） | 冒险结构 adventure_finished 载荷 | Read | 末关分支数据锚（相邻域冒险结算屏消费） |
| GP 账本 | 冒险结构 GP 冒险账本 | — | 不进本屏（维持 2026-09-27 拍板） |
| 钥石入账 | 元进度 settle_adventure | Write（相邻域） | 唯一写档点不变；本屏零钥石元素（迭代 10 起，增量行迁战斗总结结算） |
Accessibility
沿用 HUD框架「可访问性基线」节全量（对比/色弱/字号/闪烁/减动效/纯鼠标/中文字体）——本屏无新增承诺。结算数字是本屏信息主载体，遵守同一字号下限与对比硬指标。
Acceptance Criteria
- 非末关通关必经本屏：三选一恰呈现一次（零自动推进）、点选后恰兑付一件（重复兑付被拒）、未选项零生效
- 三候选读数可见且与 bonus_pick 载荷一致（件名称 + 效果行值）；同种子同三候选
- 部分回血兑付行可见且封顶上限；满血回 0 呈合法态文案
- 同调位替换子交互：满位收新触发 N+1 选 N，丢旧收新与放弃新件两路终态恒 ≤ 同调位
- 末关通关分支正确直通冒险结算（不发三选一与回血），冒险摘要五件事完整
- 确认前冒险状态冻结（无后台推进、无战斗事件串扰）；选择停点中断 → 续玩已选不丢失（候选一致性=停点快照承载的实现现状、非验收义务——2026-10-01 用户裁决）
- 呈现遵循 HUD框架 可访问性基线（对比 ≥4.5:1、字号下限、纯鼠标可完成；减动效 = 静态化）
- 本屏零钥石元素、零 GP 元素（禁入清单机检随冒烟断言）
Open Questions
- GP 增量展示面归属——已收口（2026-09-27 用户拍板）：战斗胜利出现战斗总结结算、展示获得的资源（GP 增量+总量；迭代 10 起追加 Boss/精英钥石增量行）；战斗失败出现冒险总结结算、确认后回存档首页。本屏不承载 GP 与钥石，无遗留。两面呈现 spec：settlement-summary.md v1.1
- 末关分支形态：末关通关时直通冒险结算（现行维持）——随完整屏形态实装批一并定
- 钥石呈现三面化——已收口（迭代 10 契约 6 推荐案）：战斗总结结算（Boss/精英击杀增量行）+ 冒险总结结算（收束明细）+ 营地存量——「进账时刻 / 收束明细 / 存量可用」不同义不构成重复展示；本屏旧「钥石增量+累计」呈现随大奖励重构退役
- 视觉终稿：以表现层样张过审为前置（06 待办登记）；本 spec 的 AC 为功能性判据，不含视觉终稿判据。本批渲染层验证冻结（用户 2026-10-01）——实装后目检清单随批交付，实机目检待用户批准后补闸
- 替换子交互视觉形态：本批锁定功能性判据（N+1 选 N、两路出口、终态 ≤ 上限）；卡面/面板布局视觉归样张批
修订记录
| 日期 | 改动 |
|---|---|
| 2026-09-27 | 初稿（UX 文档欠账处置批，用户拍板建档）：义务锁定版——大奖励三件套/钥石入账/清库反馈预留成文；现行载体（_inter_overlay 与 BattleEndOverlay 复用）与代码锚如实登记；GP 归属两处登记不一致挂 OQ1，拍板前不新增 GP 呈现义务 |
| 2026-09-27 | GP 归属拍板对齐批（用户口径：战斗胜利→战斗总结结算展示获得资源〔目前 GP〕；战斗失败→冒险总结结算→确认回存档首页）：OQ1 收口——GP 总量+增量归战斗胜利总结结算（battle.md OQ14 为准），本屏不承载 GP；OQ3 收口——「结算画面」指认 = 冒险总结结算，大奖励屏钥石进账 + 冒险总结结算明细两处并存维持；信息归属 GP 移入禁入清单；Data Requirements GP 行改零访问；06 归属行同步修正 |
| 2026-09-27 | 关卡画面 UX spec 建档联动：§Navigation Position 下游屏行挂 level-map.md 屏级 spec 指针。零机制改动 |
| 2026-10-01 | 三选一选择交互重写（迭代 10 奖励重构批——用户 2026-09-30 拍板案丙；T2 UX spec 卡）：①Purpose/载体/导航/进出/层级/状态/交互/数据全节重写——「大奖励三件套快照展示」退役，改「部分回血反馈 + 提升三选一三卡点选 + 确认兑付 + 同调位替换子交互」；②钥石元素全屏退役（增量行迁战斗总结结算，禁入清单机检化）；③交互范式 = choice_box 按钮族 + 选路两段式复用，零新增原语；④AC 五条改写 + 断点中断/减动效/禁入机检三条新增；⑤OQ3 改钥石三面化收口、OQ5 改替换子交互视觉归样张批 |