0 Fork 0

Files

T

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 零命中，本批未碰，避免两个换名批纠缠。

2026-10-05 06:50:44 +08:00

15 KiB

Raw Blame History

Interaction Pattern Library（交互 pattern 库）

Status: Complete（核心 8 成文〔2 号已退役留档〕+ 12 目录占位） Author: user + ux-designer Last Updated: 2026-09-20（退役术语扫描批：pattern 2 退役留档、pattern 8 消费面注记、未生效类行枚举收敛，见文末修订记录） Template: Interaction Pattern Library 来源: design/gdd/ux/battle.md（2026-09-12 /ux-review APPROVED）已拍板内容的成文固化——本库不引入新设计决策

Overview

用途：ui-programmer 实现时引用既有 pattern，不重复发明；实现中出现新 pattern 时必须回写本库（team-ui Phase 3 义务）
输入约束：PC / Keyboard-Mouse 主（全部操作纯鼠标可完成）、Gamepad Partial 非 MVP、Touch None
视觉依据：art-bible §3.3（半拟物：容器穿戏服、数据素面；直角=逻辑信息、圆角=可触摸物件）、§4（彩为世，墨为信——逻辑信息一律近黑暖墨族）
全局语义红线：无任何信息仅靠色相承载（art-bible §4.5 色弱安全清单逐对成立）；明度分层（§2，2026-09-29 v3.0——状态与情绪区分仍只用色相/饱和/运动/元素四手段；空间纵深与光照可走明度带）

Pattern Catalog

#	Pattern	类别	状态
1	双源拒绝反馈	Feedback	成文 ✓
2	原位窗口激活	Overlay	已退役（2026-09-15 下线，留档）
3	逐行兑现明细带	Data Display	成文 ✓
4	悬停预承诺光标	Input	成文 ✓
5	点阵资源显示	Data Display	成文 ✓
6	模态 overlay 层级纪律	Modal	成文 ✓
7	破坏性确认异位	Feedback	成文 ✓
8	禁用态即理由	Feedback	成文 ✓
9	常驻意图徽标	Data Display	已实现（enemy_card_view.gd——规格全文待补）
10	一次性非模态教学提示	Feedback	已实现（chord 提示——规格全文待补）
11	tooltip 规范	Feedback	已实现（状态/道具悬停——规格全文待补）
12	单意图帧批次提交	Input	已实现（main.gd 组合根——规格全文待补）
13	状态效果槽	Data Display	已实现（status_slot_row.gd——规格全文待补；载体变更留档：C 区四槽已退役，现役载体=B 区站桩伴随件）
14	步进进度条	Navigation	已退役留档（level_strip_view 已删，节点态承载进度）
15	移动路径预览	Input	已实现（board_view.gd BFS 蓝点——规格全文待补）
16	清图/换图演出编排	Feedback	已实现·占位级（board_fx_view.gd 金粒彩纸——规格随战斗表现美术批补）
17	胜利/失败终局编排	Feedback	已实现·占位级（battle_end_overlay.gd——规格随战斗表现补）
18	Boss 遭遇演出	Feedback	已实现·占位级（紫赤影子——规格随战斗表现补）
19	库存常读列表	Data Display	已实现（inventory_panel_view.gd——规格全文待补；载体变更留档：现行载体=C 区道具槽）
20	标准控件组（button/progress bar/list）	Control	已实现（ui_kit.gd 直角细线/凸圆角——规格全文待补）

MVP 未使用标准控件（不入库）：toggle / dropdown / input field / tab bar——战斗屏无此需求；TunePanel slider 为调试专用。

Patterns（核心 8）

1. 双源拒绝反馈（dual-source rejection feedback）

Category: Feedback Used In: 战斗屏（棋盘/资源全部意图动作）

Description: 玩家意图被核心拒绝时，反馈必须同时做到：(a) 每次拒绝玩家可感知（防静默拒绝读感欺骗）；(b) 来源可区分——棋盘面（排雷玩法判，携 sub_reason 封闭枚举）/资源面（行动经济判，客户端推断）/相位（排雷玩法 ActionOutcome）三源各异；(c) 图标+文案双通道，非色相独载。

Specification:

触发：ActionOutcome{accepted=false, reject_reason, sub_reason} 返回值驱动（拒绝无事件外发——排雷玩法发射面封闭，实现层不得等待拒绝信号）
反馈映射：board_face → 目标格危险红 #A8321F 边框闪（拒绝语义红族——旗朱→封印紫→封印黑 #000000，2026-09-28 用户拍板现行） + toast 具体原因（sub_reason→文案映射表：not_adjacent/target_revealed/target_concealed/flag_present/flag_absent/no_path/out_of_catalog）；resource_face → 对应资源数字脉冲（AP/RAP）+「AP 不足 · 剩 0 点」式文案；phase → toast（结算中/非挖掘期）
即时性：拒绝当帧呈现；toast 自动消退 2.5s
voided 区分：作废 ≠ 拒绝（零效果零扣费零事件）——须独立文案如「本轮已清图，停手未执行 · 剩余 AP 已作废」，至少 stop 作废可感知
Accessibility：危险红边框闪为形状+运动通道；文案常驻

When to Use: 任何意图提交被拒绝时（唯一拒绝呈现通道） When NOT to Use: 成功反馈（走动作本身的直接视觉反馈通道）；voided 语义场景（作废文案独立）

Reference: battle.md §States 拒绝/作废子态、§Interaction Map；排雷玩法×6⑥、行动经济双源契约

2. 原位窗口激活（in-place window activation）——已退役留档

退役注记（2026-09-20 退役术语扫描批补标）：唯一消费面"轮末道具使用窗口"已随 2026-09-15 可选类道具删除整体下线（地图战斗资源批），本条原 Specification 整段退役不再装载呈现义务；编号留空防后续 pattern 交叉引用失锚（照 battle.md 布局决策 2 先例）。

3. 逐行兑现明细带（line-by-line settlement feed）

Category: Data Display Used In: 战斗画面区底部（结算期第一注视点）

Description: 轮末结算逐行流水实时呈现 + 可回看——「扫雷之因逐行兑现为战果」（P2 归因）的承载面。挖掘期收起为 1 行上轮摘要；结算期展开 84px 实时流；点击开完整回看 overlay。

Specification:

数据源：战斗结算步骤流（9 类行封闭协议（现行）；公共字段 type/source_class/origin_cell/round_index/display_name/value/highlight?）；无来源行 = 断言失败
行模板：「{行为} {值} → {目标}（来源）」——来源标注（第 N 轮 · 安全格式）；行文案最长 token = 来源标签（4 汉字封闭枚举），模板预留 40% 膨胀宽度
聚合纪律：未生效类行（奖励未生效——现行 9 类行协议唯一未生效型，2026-09-20 收敛）按聚合计数呈现（防逐行惩罚轰炸）；衰减行聚合计数；效果行 value=单次贡献值、禁与 pool_value（池合成值）相加呈现；零值行可见不吞（免伤轮归因不断点）
高亮：highlight 字段 {flag_hit, clear_reward_h2, perfect_broken} → 金框强调；完美排雷 = 独立高光行 + 全屏喝彩级反馈
布局：固定槽高 + clip_contents；正文 ≥14px；数值暗底高对比；未生效类行带 icon/划线形状冗余
击杀标记呈现（H3 数据源 = 战斗结算流水击杀结果字段）

When to Use: 任何「因果可归因」的逐行流水呈现 When NOT to Use: 自造行类型/字段（9 类封闭枚举（现行）——增删 = 接口漂移，须走《战斗结算》修订）

Reference: battle.md §Component Inventory 结算明细带、§AC 信息与归因；归档《战斗结算》（b1-settlement.md）Core Rule 14 / Visual Req

4. 悬停预承诺光标（hover pre-commitment cursor）

Category: Input Used In: 扫雷图 BoardView

Description: 左键双义（已开格=移动 / 未开相邻格=挖）的消歧完全依赖格态一瞥可辨 + 悬停光标区分——误挖不可逆（1 AP + 可能触雷）的感知保险。

Specification:

光标三态：移动（箭头）/挖（镐）/旗（旗形）——按悬停格态与键位自动切换
目标格边框高亮常驻
可挖域常驻指示：小人 8 向相邻未开格呼吸微光（挖掘期唯一在动元素——art-bible §2.1）
非相邻格：禁止光标 + 首次 toast「需先走近（点击已开格移动，免费）」
提交：悬停仅预承诺，点击才提交意图（单意图帧批次——目录 #12）
chord 首遇提示：怀旧玩家双击快开尝试时一次性 toast（含排雷玩法登记锚点「点数字格可移动小人」）

When to Use: 一键多义且后果不对称的操作面 When NOT to Use: 单义控件（直接点击反馈即可，勿加光标层）

Reference: battle.md §Interaction Map；排雷玩法×6②③

5. 点阵资源显示（dot-matrix resource display）

Category: Data Display Used In: AP 条（RAP 读数已并入，独立 RAP 框不存在）

Description: 离散点阵 + 数字双承载的资源显示——点阵为图形载体（本地化零成本、一眼可读余量），数字为精确值。

Specification:

形态：●●●●●○○○ + 「5/8」；直角细线数据框（信息=直线直角，art-bible §3.3）
更新触发：组合根每次调用返回后重查（行动经济无推送信号——实现层不得等待资源变更事件）
拒绝反馈：资源不足时数字脉冲（pattern 1 的 resource_face 腿）
Accessibility：点阵=形状通道、数字=文本通道；对比 ≥4.5:1

When to Use: 小整数离散资源（≤16 量级） When NOT to Use: 大数值/连续量（用直角细线进度条——目录 #20）

Reference: battle.md §Layout C/D 区；行动经济 UI Requirements

6. 模态 overlay 层级纪律（modal overlay discipline）

Category: Modal Used In: 图例面板、结算明细回看、胜利/失败终局 overlay

Description: 任何模态覆盖层打开时必须隐藏/锁定其遮挡的交互物，关闭恢复——防「看不见但可点」的幽灵输入（垂直切片缺陷⑤教训，场景级断言强制）。

Specification:

打开：遮挡物隐藏或禁用 + 输入锁定；单一模态栈（无叠模态）
关闭：恢复被遮挡物；关闭按钮/再点入口切换
内容：固定槽高 + clip_contents（缺陷①——悬停文案换行不得推挤布局）
验收：场景级断言「打开时遮挡物隐藏/输入锁定」为每个模态 overlay 的强制 AC（battle.md 场景级测试节）

When to Use: 全屏打断级信息、只读回看、仪式性终局 When NOT to Use: 与常读面板同域的窗口态（原 pattern 2 原位激活已随道具窗口退役——此类场景当前无消费面）；独立屏（2026-09-28 起：关卡画面形态升格为独立屏退出本 pattern 族——其屏级语义见 level-map.md；节点/商店覆盖层在关卡画面激活域内弹出时仍属本 pattern，遮挡/恢复语义复用单一模态栈）

Reference: battle.md §AC 场景级测试；缺陷①⑤（production/session-state entry 17）

7. 破坏性确认异位（destructive-confirm position offset）

Category: Feedback Used In: 弃图刷新（RAP−8 消耗 + 旧板弃置）

Description: 消耗性/不可逆操作的确认交互与常规确认不同位——位置通道是色盲安全冗余（art-bible §4.5 清单 #7：UI 红/金强调对需图标+文案冗余，且破坏性确认不得与常规确认同位）。

Specification:

弃图刷新：确认微交互显式呈现全部代价（RAP−8 · 旧板旗随旧板作废提示）；确认交互位置与常规确认不同位
双通道：图标 + 文案冗余
拒绝路径：RAP<8 → pattern 1 resource_face（EC13 合法拒绝可见）

When to Use: 任何消耗资源/不可逆的操作确认 When NOT to Use: 无代价操作（直接执行 + 直接反馈）

Reference: battle.md §Accessibility、§AC 交互与反馈；art-bible §4.5 #7

8. 禁用态即理由（disabled-state with reason）

Category: Feedback Used In: （现无消费面——原道具窗口满血治疗包随可选类道具退役 2026-09-15；本条保留为通用模式，消费面随秘宝 Alpha 重设计回归）

Description: 禁用不许静默——灰置必须伴随可见的禁选原因（tooltip/toast），防「为什么点不动」的困惑。

Specification:

形态：灰置 + tooltip「HP 已满 · 禁选」；点击无效 + 原因 toast 兜底
语义区分：满血 = 零收益守卫（禁选、不烧包）≠ 缺血不足（超量 clamp 部分回复，不禁选）
usable_now 由战斗结算组装进窗口载荷（地图战斗资源零跨系统读）——呈现层只消费不推断

When to Use: 任何可见但不可交互的元素 When NOT to Use: 完全隐藏的不可用功能（不存在的东西无需解释）

Reference: battle.md §Interaction Map；地图战斗资源 Rule 7 / AC-14

Gaps & Patterns Needed

目录 #9–#20 已全部实现（2026-09-12 战斗屏实现批，冒烟 149/149 + 三探针全绿）；规格全文回写 = HUD框架正式化批义务
实现期新增技术件（不单独立 pattern，规格归并）：去饱和+金橙状态切换 = 逐格共享 ShaderMaterial（明度不变，gl_compatibility 安全）；敌人死亡残位 = 卡体灰化+碎裂禁瞬消（归入 #17 终局编排规格）
MVP 未使用标准控件：toggle / dropdown / input field / tab bar（无需求不设占位）；TunePanel slider 为调试专用不入库
实现偏差规则：pattern 近似但不完全适配时，实现层不得静默变体——登记偏差交 ux-designer 复核后回写

Open Questions

目录占位项的补全时点 = 实现期随批回写（owner：ui-programmer → ux-designer 复核）
Gamepad 批次引入时，需为 pattern 4/12/15 增补手柄映射节（焦点序已在 battle.md OQ8 留位）

修订记录

日期	改动
2026-09-15	雾格残留清理：pattern 1 无改；pattern 4 的悬停预承诺消歧依据改按格态两态表述；目录 #10 一次性非模态提示的已实现说明去掉雾首遇、只留 chord 提示。pattern 库不引入新决策
2026-09-20	退役术语扫描批（用户拍板）：pattern 2 原位窗口激活退役留档（唯一消费面轮末道具窗口随 2026-09-15 可选类道具删除下线——编号留空防交叉引用失锚，照 battle.md 布局决策 2 先例）；pattern 8 禁用态即理由 Used In/Reference 去道具窗口引用（保留为通用模式）；聚合纪律未生效类行枚举收敛为奖励未生效

15 KiB Raw Blame History Unescape Escape

Interaction Pattern Library（交互 pattern 库）

Overview

Pattern Catalog

Patterns（核心 8）

1. 双源拒绝反馈（dual-source rejection feedback）

2. 原位窗口激活（in-place window activation）——已退役留档

3. 逐行兑现明细带（line-by-line settlement feed）

4. 悬停预承诺光标（hover pre-commitment cursor）

5. 点阵资源显示（dot-matrix resource display）

6. 模态 overlay 层级纪律（modal overlay discipline）

7. 破坏性确认异位（destructive-confirm position offset）

8. 禁用态即理由（disabled-state with reason）

Gaps & Patterns Needed

Open Questions

修订记录

15 KiB

Raw Blame History