gplan-2/design/ux/battle.md

UX Spec: 战斗屏（Battle Screen）

Status: Complete — /ux-review 修订落稿（2026-09-12，blocking 7 项已修，待复检） Author: user + ux-designer Last Updated: 2026-09-12 Platform Target: PC (Steam)——Keyboard/Mouse 主（全部操作纯鼠标可完成）、Gamepad Partial 非 MVP、Touch None（同 technical-preferences） 上游修订依赖: 弃图刷新挖掘期受理已随 D4 落稿上游（2026-09-12：A3 Active 受理 + 每轮上限 2 次、A2 Active·仅刷新路径装板、B1 refresh_board 编排 + 恒 same_board、registry rap_rules 同步——见 OQ12） Template: UX Spec 覆盖子屏: 挖掘阶段主界面 · 轮末自动战斗结算（B1 明细屏） · 道具使用窗口（B4/B1 域屏） · 胜利/失败终局 · 结算明细回看 输入义务: A2×6 + A3 + A4×3 + B1×3 + B2×4 + B3×4 + B4×5（systems-index 门禁增补记录，缺项即 blocking——承接落点见 §13 义务对照表）

---

Purpose & Player Need

战斗屏是 Dungeon Sweeper 的核心玩法屏——游戏的全部 agency（排雷规划 + 轮末资源决策）都发生在这里。玩家在此屏完成完整轮次循环：用本轮 AP 在扫雷图上挖掘/标旗 → 主动停手或 AP 耗尽 → 观看轮末自动战斗结算逐行兑现 → 下一轮。

一句话目的：让"我算对了"的推理过程与它的战果兑现同屏可见、互为因果。

• 扫雷图区承载 P1（推理掌控感）：数字是主角，一切服务信息可读
• 战斗画面区承载 P2（规划的延迟兑现）：扫雷之因逐行兑现为战果，全程可见可归因
• 角色信息/道具区承载规划面：状态、资源、库存常读，支撑"往雾区推进/囤刀待机"类决策（B4 可证伪信号的 MVP 观测面）

若此屏缺失或难用：推理与兑现分裂（自动战斗沦为无聊过场——已登记创意风险）、逐行归因不可见（P2 失败）、AP/RAP/库存不可读（规划失去原料）。

---

Player Context on Arrival

• 首次到达：从关卡首节点（战×2 的第一战）进入。MVP 无引导流，A4 雾首遇提示、chord 肌肉记忆提示等非模态提示承担首次教学（见 §States）
• 到达前刚在做：关卡节点链上点击战斗节点（LevelRunner 推进）；或上一场战斗胜利后点下一节点
• 情绪状态：棋手式清明专注（art-bible §2.1，能量 2/10）——挖掘期画面必须无杂音；结算期转为清算爽感（7/10）
• 到达方式：游戏推进送入（非自愿导航），进入即处于挖掘阶段（棋盘已 install、初始 3×3 已展开、小人出生）

⚠️ Player journey map 未建（design/player-journey.md 不存在）。模板位于 ux-design 技能；建议在本 spec 进入实现前补建，以校准各阶段情绪曲线。

---

Navigation Position

存档 → 冒险 → 关卡（节点链，C1-lite） → 【战斗屏】
                                          ├─ 胜利 → 节点奖励/恢复覆盖层 → 下一节点（下一场战斗屏）
                                          ├─ 胜利（末节点 Boss）→ 关卡结算（level_clear，库存清空反馈）→ 下关
                                          └─ 失败 → 冒险终结 → 返回存档/营地

战斗屏是上下文相关屏（仅由战斗节点进入），非顶层常驻。关卡内节点进度常驻屏顶（A 区），玩家始终知道自己身处链中第几环。

• 上游屏：关卡节点链（节点地图形态 = 线性，C1 已裁剪为线性第一关）
• 下游屏：节点奖励/恢复覆盖层（NodeOverlay，已有 demo 组件——建议后续单独出 spec design/ux/node-reward.md）
• 平行屏：结算明细回看 overlay（本屏内域屏）、图例面板 overlay（本屏内域屏）

---

Entry & Exit Points

进入：

Entry Source	Trigger	Player carries this context
关卡战斗节点	点击节点（LevelRunner 推进 encounter）	携带 HP（跨战斗延续）、库存（关卡域延续）、RAP=0（战斗域新开）
上一场战斗胜利 → 下一节点	同上	同上

离开：

Exit Destination	Trigger	Notes
节点奖励/恢复覆盖层	敌方全灭（B1 判定段 verdict=win）且非末节点	不可逆：battle_over 已发生，RAP 清零
关卡结算	Boss 战胜利 → level_clear	不可逆：库存清空（须可见反馈，B4 D1×⑤）
冒险终结	主角 HP=0（verdict=lose）	不可逆：Roguelike 死亡重开（art-bible §2.5 温柔惋惜调性）
无中途退出	—	MVP 不设战斗内放弃/暂停菜单（回合制无时间压力；如需暂停留 Playtest 诊断按钮，调试用）

---

Layout Specification

Information Hierarchy

本屏必须传达的全部信息，按注视优先级分五层：

1. 扫雷图本体（第一注视点，挖掘期占视觉预算大头）：四格态（已开 0 格地板/已开雾格无字/未开格/未开雾格——A2 D1×6② 一眼可辨）、数字、旗、小人、可挖域（8 向相邻常驻指示）、变异纹理（迷雾）
2. 本轮行动资源：AP 余量（决定还能挖几格）、停手/弃图刷新按钮——紧贴棋盘上缘（动作发生地）
3. 战果兑现面（结算期为第一注视点）：敌人血条变化、逐行结算明细、高光（完美排雷/标中旗）
4. 规划面（边缘注视，常读）：HP、攻击、RAP 池、状态效果（己方/敌方）、库存列表、敌人意图徽标与顺位
5. 进度语境：轮次/阶段指示、关卡节点进度、雾图例入口

依据：挖掘期玩家视线锚定棋盘（art-bible §2.1"视线始终被数字牵引"）；结算期视线转向战斗画面区（§2.2"兑现光带逐行横扫"）。规划信息必须常读但不得抢焦——这正是用户布局图三分下栏的合理性：动作区居中，规划区两翼。

Layout Zones

采用用户拍板的布局图（2026-09-12），按 1280×800 基座（ADR-0002）落尺寸：

区	位置与尺寸	内容
A 关卡进度条	全宽 × 28px 顶栏	节点链步进（⚔战 ◆道具 ⚔战 ⚔战 ♥恢复 👑Boss），当前节点高亮
B 战斗画面	全宽 × 252px	英雄卡（左）+ 兑现演出区（中）+ 敌人卡 ×1–3（右）；底部结算明细带（24px 摘要 / 结算期 84px 实时流）；顶部中央轮次·阶段指示
C 角色信息	左下 240px × 520px	HP 条、攻击值（含修正显示）、RAP 池、状态效果槽（固定 4 槽）、小人立绘占位
D 扫雷图	中下 ~760px × 520px	顶部 AP 条（44px：左——AP 点阵 + 停手按钮；右——图例按钮 + 弃图刷新按钮〔雷图右上角，2026-09-12 拍板〕）；棋盘主体（居中，格 36–45px 见方）；toast 槽（上缘内侧）
E 道具	右下 280px × 520px	库存常读列表（固定槽高 + clip_contents——缺陷①教训）；窗口期原位激活为道具使用窗口

布局决策 D1（本 spec 最大决策，用户拍板）：常驻双舞台分屏——战斗画面与扫雷图同屏常驻，挖掘期敌人待机可见，结算期不切场景。

• 备选（已否决）：Peglin 式"结算时才切入独立战斗场景"——切换打断推理心流，且资产管线成本翻倍
• 对 B5 双舞台陷阱的输入：game-concept 登记的"战斗发生在棋盘上还是独立场景"悬念，由本布局裁决为第三形态：同屏双舞台。B5 前的"战斗表现美术测试"（一屏样张）应按此布局出样
• 敌人不占格（B2 已锁）与本布局自洽：敌人实体只存在于 B 区，棋盘永远只有数字/旗/小人/变异

棋盘格尺寸公式：cell = floor(min(D宽−padding, D高−AP条−padding) / N)，N∈{10,12}（A1 D1–D4 行）。1280×800 下 12×12 → 36px，10×10 → 45px。数字字号 ≥ 格高的 50%，像素字体整数倍缩放（canvas_items stretch 保证清晰，ADR-0002）。

Component Inventory

区	组件	类型	内容	交互	现有 demo 组件
A	LevelStripView	步进条	节点链 + 当前位置	只读（点击节点不可跳）	✅ level_strip_view.gd 迁移
B	英雄卡	卡片	小人像、HP 条、攻击值、状态效果槽 ×4	只读	HUDView 拆分
B	敌人卡 ×1–3	卡片	敌像、血条、顺位徽标、意图徽标、行为环点、状态槽（含敌方 side 池口径：伏击层数为全体敌人共享单值、各卡同值呈现——数据源 = B1 流水经 B3 投影，B2×4④）	只读	新建
B	轮次·阶段指示	标签	"第 N 轮 · 挖掘中/结算中/道具窗口"	只读	新建
B	结算明细带	滚动列表	结算期逐行流水（B1 13 类行协议）；挖掘期收起为上轮摘要 1 行	点击展开明细回看 overlay	battle_log_view.gd 改造
B	结算明细回看	模态 overlay	完整流水逐行（四类行呈现，B4 D1×③）	关闭	battle_log_view.gd 改造
C	HP/攻击/RAP 显示	直角细线数据框	当前值/上限、修正来源角标	只读；RAP 清零有可见反馈	HUDView 拆分
C	状态效果槽 ×4	图标槽	effect_id→icon（形状+色相双通道）、层数角标、剩余结算次数点	悬停 tooltip（来源+语义）	新建（B3 D1×①）
D	AP 条	点阵 + 按钮组	本轮 AP 点阵、停手按钮（左）、弃图刷新按钮（右端·雷图右上角；RAP−8 · 本轮剩 N 次——上限 2 次已随 A3 2026-09-12 修订生效）	点击提交意图	HUDView 拆分
D	BoardView	网格	棋盘全部格态 + 小人 + 旗 + 雾纹带 + 奖励身份 icon（已开格；绘制优先级 数字>小人>旗>奖励徽章>变异纹带>底色——徽章不进数字区，样张验收项）	左/右键意图提交	✅ board_view.gd 迁移
D	悬停预承诺光标	光标态	移动/挖/旗三语义光标 + 目标格边框高亮	自动	新建（A2 D1×6③）
D	可挖域指示	常驻微高亮	小人 8 向相邻可操作格	自动	新建（A2 D1×6③）
D	移动路径预览	路径高亮	悬停已开格显示 BFS 路径（合法性指示）	自动	新建（A2 D1×6⑤，裁决见下）
D	toast 槽	非模态提示	拒绝原因（双源）、voided、满层溢出、雾首遇、chord 提示、零合法板告知	自动消退 2.5s	新建
D	图例按钮 + 面板	按钮+模态 overlay	格态/变异/雾语义图例（"迷雾 = 无雷盲区"条目恒在）	开/关	新建（A4 D1×②）
E	库存列表	固定槽高列表	逐件：icon+名称+属性简述+状态；枚举序 = stock 受理序（E21）	悬停 tooltip（完整描述+触发注记）；窗口期点选	item_window_overlay.gd 改造
E	道具使用窗口态	面板原位激活态	"轮末道具窗口 · 至多选 1 件"+ 时机指示 + usable_now 禁选态 + 跳过按钮 + 触发政策注记	点选/跳过	✅ item_window_overlay.gd 改造（形态裁决见下）
全屏	胜利/失败 overlay	模态	金蜡封/暮蓝收旗 + 判定行 + 明细回看入口	继续/下一节点	node_overlay.gd 扩展
调试	TunePanel	调试面板	atk%/hp% 滑条 + 批量模拟（正式侧归 C4，切片调试入口保留）	调试	✅ tune_panel.gd 保留

布局决策 D2 — 道具窗口形态 = 右栏原位激活：窗口触发时 E 区面板点亮描边、标题切换为窗口态，棋盘侧去饱和 + 金橙色相偏移锁输入（明度不变——art-bible §2 明度恒定合规化，2026-09-12）。

• 备选（已否决）：中央模态弹窗——遮挡结算演出首屏（授予段刚完成的视觉记忆），且库存常读位置与窗口位置分离造成空间记忆断裂
• 依据：窗口期棋盘输入本就不竞争（结算期棋盘不可交互，A2 单意图帧先例），无模态必要性；B1 窗口锚点 = 授予段后、增益/减益段前——玩家需同时看库存与刚到手的奖励

布局决策 D3 — 移动路径预览 = 合法性指示（A2 D1×6⑤ 悬案裁决）：悬停已开格时高亮 BFS 路径（小人蓝细线点迹），移动执行为 ≤150ms 短滑。

• 备选（登记不采纳）：穿行动画轨道——移动免费高频，动画时间税违反 P4 点击摩擦护栏（每轮输入动作:AP ≤2 的观测假设）；正式版若 playtest 反馈"移动太瞬"再议（留痕）

布局决策 D4 — 弃图刷新 = 挖掘期当场换图（2026-09-12 用户拍板，同日落稿上游）：按钮置 AP 条右端（雷图右上角）。点击即当轮就地换新图继续挖——AP 不重置、剩余 AP 保留，RAP−8，本轮上限 2 次。

• 上游修订（2026-09-12 已落稿，OQ12）：① A3 request_refresh Active 相位受理 + 每轮上限 2 次（Waiting 代理退役）② A2 装板受理域增 Active·仅刷新路径 ③ 编排 owner = B1 refresh_board（A3 扣费 → A2 retire → A1 generate → A2 install → B4 roll_board 恰一次；无结算段、无 round_end——B1 编排唯一性原则保持）④ 旧板旗随旧板作废（零兑付、旗 AP 不返还——A2 EC11 全量重置承载；确认微交互须显式提示）。经济预警：当场刷新无结算发生，原「敌方时间税」自惩失效——A3 OQ3 弃图率/刷新率预警阈值联动复核。
• 备选（已否决）：结算期决策提示（Waiting 内联）——结算期不做刷新决策（用户拍板）；挖掘期预承诺 stop+reroll 复合——决策即终轮，不符「换图继续挖」语义。

敌人意图线索映射目录（B2×4① 成文占位，2026-09-12）：

enemy_id	视觉状态（意图线索）	强度档位编码	环长编码
grub（蛆虫）	攻击 ×1 态	小体量墩形 = 轻击	环点 1
ambusher（伏击者）	攻击 / 蓄力 / 重击 ×3 态	垂直延伸体量 = 重击（heavy_multiplier）	环点 = 拍数

• 预告时序 = 下一拍预告（当前拍视觉状态），挖掘期全程可见；结算期不另设意图播片（B2 Rule 8⑤）
• 映射键 = enemy_id，跨 run 恒定、禁止重掷（B2 Rule 8③）；形状 + 色相双通道（art-bible 约束）
• 资产定稿归 B5；本表为 D1 侧成文占位（B2 Visual Req 2 口径：grub 1 态 / ambusher 3 态）

ASCII Wireframe

1280 × 800 ────────────────────────────────────────────────────────────────────
┌─[A] 关卡进度条 28px ─────────────────────────────────────────────────────────┐
│   ⚔──⚔──◆──⚔──⚔──♥──👑        (当前节点高亮，已过节点暗金)                    │
├─[B] 战斗画面 252px ──────────────────────────────────────────────────────────┤
│ ┌────────────┐                              ┌──────────┐ ┌──────────┐        │
│ │ 英雄卡      │    第 3 轮 · 挖掘中           │ ①蛆虫    │ │ ②蛆虫    │        │
│ │ [小人像]    │                              │ HP▓▓▓░   │ │ HP▓▓░░   │        │
│ │ HP▓▓▓▓░    │      [ 兑现演出区 ]           │ 意图:爪击 │ │ 意图:蓄力 │        │
│ │ 攻 6 (+50%) │   (结算期: 光带→弹道→受击)    │ 环 ●○○○  │ │ 环 ●●○○  │        │
│ │ 状态 ⬆2 ·🛡1 │                              │ 状态 ⚡2  │ │ 状态 🛡1  │        │
│ └────────────┘                              └──────────┘ └──────────┘        │
│ ├─ 结算明细带 ────────────────────────────────────────────────────────────┤  │
│ │ ▸上轮: 主角攻击9→蛆虫-9 | 攻击+50%(1结算) | 伏击+3×2 …        [展开明细▾] │  │
│ └────────────────────────────────────────────────────────────────────────┘  │
├─[C] 角色信息 240px ───┬─[D] 扫雷图 ~760px ────────────┬─[E] 道具 280px ─────┤
│        520px          │           520px               │        520px        │
│ ┌──────────────────┐  │ ┌───────────────────────────┐ │ ┌─────────────────┐ │
│ │ HP   42/50 ▓▓▓░  │  │ │ AP ●●●●●○○○  5/8          │ │ │ 道包 · 关卡域    │ │
│ │ 攻击 6  (+50%)    │  │ │ [⏹停手]                   │ │ │ (窗口态标题位)   │ │
│ │ RAP  ▓▓▓░  3/8    │  │ │   [?图例] [↻刷新 8|剩2]   │ │ ├─────────────────┤ │
│ ├──────────────────┤  │ │ ┌─toast────────────┐      │ │ │ 🗡 小刀          │ │
│ │ 状态效果          │  │ │ │AP不足·剩0点       │      │ │ │  伤害 · 一次性   │ │
│ │ ⬆攻击+50% ○1     │  │ │ └──────────────────┘      │ │ ├─────────────────┤ │
│ │ 🛑减攻−65% ○1     │  │ │  12 12  1  ░  2  ▓▓ ▓▓    │ │ │ 🗡 精工短刀      │ │
│ │ (槽×4 固定)       │  │ │  12  █  1   1  2  ▓▓ ▓▓   │ │ │  高伤 · 一次性   │ │
│ ├──────────────────┤  │ │   1  2  2  🚩 █  2  1     │ │ ├─────────────────┤ │
│ │ [小人立绘占位]     │  │ │   ░  1  ▓▓ 👫 1  1  ░     │ │ │ ❤ 治疗包 ×1     │ │
│ │                  │  │ │  ▓▓雾 1  1  ░  ░  2  ▓▓    │ │ │  回复 12 · 可用  │ │
│ └──────────────────┘  │ │  ( █=可挖域微光 👫=小人)   │ │ └─────────────────┘ │
│                       │ └───────────────────────────┘ │                     │
└───────────────────────┴───────────────────────────────┴─────────────────────┘

窗口态（E 区原位激活，轮末道具窗口）：
│ ┌─────────────────┐    面板描边点亮（金），D 区去饱和锁输入
│ │ ⏳ 轮末道具窗口   │    时机指示：位于授予段后、增益段前
│ │ 至多选用 1 件     │
│ ├─────────────────┤    可用件高亮可点；满血治疗包灰置+禁选原因
│ │ 🗡 小刀  [选用]   │    选中即承诺（照常消耗拍板）
│ │ 🗡 精工短刀[选用]  │
│ │ ❤ 治疗包(满血)   │    灰置 + tooltip「HP 已满 · 禁选」
│ ├─────────────────┤
│ │ [跳过]  注记*:未 │    *「未选用件随关卡结束清空」政策注记常驻
│ │ 选用件关卡末清空 │
│ └─────────────────┘

---

States & Variants

State / Variant	Trigger	What Changes
挖掘阶段（默认态）	轮次开始 / 结算完毕回 Active 相位	B 区敌人待机（意图徽标全程可见——B2 Rule 8⑤），D 区棋盘可交互，AP 条点亮；能量 2/10，唯悬停呼吸微光在动（§2.1）
结算阶段	round_end 触发（AP 尽/停手/清图）	D 区锁输入（棋盘去饱和 + 金橙色相偏移，明度不变，数字保持全对比）；B 区播放七段编排演出；明细带展开 84px 逐行滚动；阶段指示→"结算中"；能量 7/10
道具窗口态	结算授予段完成后（窗口锚点）	E 区原位激活（决策 D2）；空库存不弹窗直接跳过（B4 D1×②）；usable_now=false 禁选+原因
清图瞬间	全部安全格开完	金粒喷泉 + 彩纸 3–5s 即收（§2.3）；清图奖励行强调呈现（H2，B4 D1×④——金框高亮行）；随后换新图 install
完美排雷高光	B1 高光判定（全图标中/零误标类）	全屏喝彩级反馈（§2.2 最高档）：金光带加倍扫射 + 「完美排雷 ×2」横幅——P2 爆发兑现节点（创意风险 #2 落点）
标中旗高光	flag_judged{hit=true}	该旗化暴击弹道加重 + 明细行金框——chord 缺席的即时兑现补偿（创意风险 #3 落点）
敌人死亡呈现	敌 hp=0（流水行击杀标记）	该敌人卡血条归零 → 卡体灰化 + 碎裂退场（禁瞬消——B2 资产下限「死亡瞬间须可辨识、不得直接消失」，同等 blocking）；战斗段短路的重击被掐灭不产行动明细行，由行序可推断（B1）；动画密度归 B5，呈现语义在本 spec
胜利终局	verdict=win	金蜡封落于扫雷图区中央（§2.4 字面锚定），全屏暖白金 overlay；判定行 + 「下一节点」；明细回看入口；状态槽全清可见反馈（B3×4④——逐槽化光收回 + 微文案「状态随战斗结束消散」，防「我的 buff 哪去了」误读）
失败终局	verdict=lose（hero hp=0，战斗段短路）	明度不变的暮蓝 #5A6C8C 氛围 overlay（全作唯一暮蓝档）；小人坐砖掸灰、插过的旗逐面化光点收回（§2.5）；判定行 + 明细回看（学习用途）+「返回」；状态槽全清可见反馈（B3×4④，同胜利）
Boss 遭遇变体	encounter=boss（遗迹守卫）	战斗开始一次性演出：紫赤 #8F2F6A 影子爬过棋盘（§2.6）；敌人卡体量最大+锐角剪影；阶段指示附 Boss 名
雾图变体（L2+）	板含雾格	雾纹带双通道呈现；首次含雾板进入挖掘阶段触发一次性首遇提示（每 run 一次）；图例恒可回看；已开雾格保留底色层淡雾 tint（与已开 0 格可判定区分——OQ8 裁决采纳 2026-09-12；tint 处视觉锚 3 最低层，不遮挡数字）；雾区全开一次性完成信号（视觉合并域 = 信号单元，禁实例级双响；EC11：双雾区呈现合并、实例独立）
空态：无状态效果	B3 EC12	状态槽隐藏 or 空槽占位——裁决：槽位隐藏，HP/攻击/RAP 上移补位（角色信息区纵向空间紧张，空槽占位浪费）；图例面板载空态说明（B3 D1×① 成文项）
空态：零库存	关卡初/清空后	E 区显示「道包空空——安全格里藏着补给」（指引性空态，非报错）
调试变体	测试模式	TunePanel 入口（demo 保留，正式侧 C4 退役）；Playtest 诊断按钮（卡死转储）

拒绝/作废子态（A2 D1×6⑥、A3 双源——每次拒绝玩家可感知）：

• 棋盘面拒绝（sub_reason：非相邻/挖旗格等）→ 目标格 旗朱 #C63D22 边框闪 + toast 文案（图标+文案冗余，色弱清单 #7）
• 资源面拒绝（AP 不足/RAP 不足）→ AP/RAP 数字脉冲 + toast「AP 不足 · 剩 0 点」
• voided（stop 被作废等）→ toast「本轮已清图，停手未执行 · 剩余 AP 已作废」——防静默改判读感欺骗

---

Interaction Map

输入前提（technical-preferences）：Keyboard/Mouse 主输入，全部操作纯鼠标可完成；Gamepad Partial 非 MVP 门禁（导航序留 Open Questions）；Touch None。

组件	动作	输入	即时反馈	结果（经组合根）
未开相邻格	挖掘	左键	格碎裂 + 连锁展开（免费）+ 奖励身份揭显	意图入当帧批次 → A2 settle_batch
已开格	移动	左键	悬停时路径预览高亮（D3）；执行 ≤150ms 短滑	意图入批（BFS 移动，免费）
未开格	插旗 / 已旗格拔旗	右键	旗落下/移除（旗朱）	意图入批（1 AP / 免费）
停手按钮	主动结束轮次	左键	按钮下压 + AP→RAP 飞行数字	settle_batch([stop])（经 A2 批次，不直调 A3——A2 D1×6①）
弃图刷新按钮（雷图右上角）	当轮就地换图继续挖	左键	确认微交互（RAP−8 代价显式 + 旧板弃置提示）；RAP<8 → 资源面拒绝可见（EC13）	request_refresh（Active 相位当场换图继续挖——AP 不重置、本轮剩 N 次扣减；上游已修订受理——见布局决策 D4/OQ12）
图例按钮	开图例	左键	模态 overlay	恒可开（A4 图例条目恒在）
结算明细带	展开回看	左键	明细 overlay	只读
状态/道具 tooltip	悬停	hover	状态 tooltip（来源+语义+剩余）；道具 tooltip（完整描述+触发注记——不含来源）	只读
道具（窗口态可用件）	选用	左键	选中态高亮 → 窗口关闭回结算流	submit_window_selection(窗口位置)——传窗口条目位置，非库存句柄（缺陷④契约）
道具（窗口态禁选件）	—	左键无效	禁选原因 toast（满血治疗包）	无
跳过按钮	跳过窗口	左键	窗口关闭	空选择序
胜利 overlay	下一节点	左键	→ NodeOverlay / 关卡结算	LevelRunner 推进
失败 overlay	返回	左键	→ 存档/营地	冒险终结

单意图帧纪律（A2 D1×6⑥）：一帧内 collected 意图整批提交，stop 点击终结当帧收集；F4 语义序仲裁为防御性兜底。悬停预承诺三态光标：移动（箭头）/挖（镐）/旗（旗形）——左键双义（移动 vs 挖）的消歧完全依赖四格态一瞥可辨 + 光标区分（误挖不可逆的感知保险）。

复合意图（A2 评估项留痕）：点击远格 = 自动 move+dig 的两击摩擦消解——MVP 不做（留痕 2026-09-12：免费移动高频，两击摩擦符合 P4 ≤2 观测假设；A2 L298 评估项）。

可挖域常驻指示：小人 8 向相邻未开格呼吸微光（§2.1 唯一在动的元素）；不可挖域（非相邻）悬停显示禁止光标 + 首次 toast 提示「需先走近（点击已开格移动，免费）」。

chord 肌肉记忆首遇提示（A2 D1×6③）：经典扫雷玩家首日尝试双击快开时，非模态 toast 每 run 一次：「本作无双击快开——插旗后轮末自动判定标中；点数字格可移动小人」（含 A2 登记锚点「点击数字格 = 移动小人」）。文案定稿权归实现期文案 pass。

---

Events Fired

项目无分析系统；本节 = 呈现层订阅的核心信号（ADR-0001 组合根直连 signal）+ playtest 遥测义务（playtest_logger.gd 已有五类行）。呈现层新遥测（写 playtest JSONL ux 行）：

Player Action	Event Fired	Payload / Data
每轮结束	ux_round_input_ratio	原始输入动作数∶AP 消耗（A3 P4 ≤2 护栏观测，A2 D1 遥测义务）
停手/清图	ux_round_exit	path_tag {stopped, ap_exhausted, cleared}（对齐上游封闭枚举）——弃图率（C3 OQ4）观测
弃图刷新（挖掘期，非轮出口）	ux_refresh_attempt	{result: accepted/rejected_rap/rejected_cap, round_refresh_index: 1..2}——刷新使用（C3 OQ6）与 OQ3 预警阈值观测；每轮 0–2 次（D4 cap=2）
窗口选用/跳过	ux_window_choice	{selected_item_id, usable_now, skip}
拒绝/voided	ux_reject	{source: board/resource/phase, sub_reason}
提示触发/关闭	ux_hint_shown	{hint_id: fog_first/chord/no_adjacent}
呈现订阅（不改核心）	A2 三事件 / B1 步骤流（13 类行协议，含终局判定行） / battle_over / level_clear	载荷 schema 成文义务见 §Data Requirements——entry 17 D1 硬性要求①

持久状态写入全部经组合根唯一路径（settle_batch / submit_window_selection / request_refresh / runner 推进）——UI 层禁直调核心写（架构七原则"依赖单向组合根"）。

---

Transitions & Animations

时刻	过渡	依据
进入战斗屏	棋盘 install 淡入（200ms）+ 初始 3×3 展开涟漪 + Boss 战先播紫赤影子爬棋盘（§2.6）	A1 install / §2.6
挖掘→结算	明细带自底展开（150ms）+ 棋盘去饱和 + 金橙色相偏移 + 阶段指示翻转	§2.2 色彩转金橙主导、饱和拉高、明度不变（状态区分经饱和/色相——art-bible §2 合规化 2026-09-12）
结算逐行兑现	光带自棋盘行起点横扫 → 开格化箭雨/旗化暴击弹道飞向敌人卡 → 受击闪白 + 血条直角递减	§2.2 承载元素；因果全程可见可归因（P2）
道具窗口	E 区描边金光点亮（非弹窗，无缩放突兀）	决策 D2
清图换新图	金粒喷泉 3–5s → 旧图碎裂淡出 → 新图 install 淡入	§2.3 短促丰收不拖节奏
RAP 清零（battle_over）	RAP 数字滚动归零 + 「随战斗结束消散」微文案	A3 可见反馈义务
敌人死亡	血条直角递减至零 → 卡体灰化 + 碎裂退场（禁瞬消）	B2 资产下限（同等 blocking）；动画密度归 B5
状态槽全清（battle_over）	状态逐槽化光收回 + 「状态随战斗结束消散」微文案	B3×4④；RAP 清零同款先例
库存清空（level_clear）	道包逐件化光点飞出 + 「剩余道具 ×N 随关卡结束清空」	B4 D1×⑤
胜利	蜡封自上落下弹跳定格 → 碎砖拼纹章 → overlay 暖金渐显	§2.4 克制不狂欢
失败	全屏明度不变转暮蓝色相 → 旗化光点 800ms 逐面收回 → overlay	§2.5 最静一拍
减动效选项	上述全部动画提供时长减半/直接跳终态开关（项目未建 accessibility 文档前，本项为 spec 内建承诺）	动议：结算逐行兑现为信息载体不可整体跳过，可加速

---

Data Requirements

Data	Source System	Read / Write	Notes
棋盘四格态/数字/雾/可挖域	A2 只读面（query）	Read	呈现刷新面 = A2 三事件信号（载荷 schema 成文——entry 17①）
BFS 移动路径	A2 compute_move_path	Read	D3 合法性指示消费
拒绝原因	A2 sub_reason 封闭枚举 + A3 资源面	Read	三源（board/resource/phase）映射文案——呈现层契约成文；资源面原因无上游载荷（A3 仅 bool + debug 诊断），客户端按动作上下文推断
AP / RAP / 本轮刷新计数	A3	Read	常显；刷新入口可用性 = RAP 读数客户端预判（RAP≥8）+ request_refresh 返回值（A3 无 can_request_refresh API——仅 bool 返回 + 只读观测量；EC13 拒绝合法可见）
结算流水行（13 类）+ 四类行	B1 流水协议	Read	逐行来源标注（P2）；聚合计数行呈现
判定 verdict	B1 判定段	Read	终局画面数据锚
敌单位 hp/顺位/意图环下一拍/enemy_id/存活	B2 只读面	Read	意图线索映射全局恒定（D1×4②）；despawn 前捕获（entry 17③——缺陷②教训）
状态效果投影（含空态/极性/溢出）	B3 投影口径	Read	极性映射数据源 = B1 SettlementTable 效果语义，非 magnitude 符号（B3 D1×③）
库存（item_id/状态/枚举序/行值投影）+ 奖励身份	B4 query_inventory / 快照	Read	reward_id 全局恒定；属性简述由行值快照投影派生（伤害/回复/增益一句话）；载荷含来源 {cell, round} 但不呈现于库存列表与 tooltip（2026-09-12 用户拍板——来源归因职责由结算明细行承载，P2 不受影响）；窗口载荷 usable_now 由 B1 组装（B4 零跨系统读）
节点链/当前节点/HP 携带	C1-lite LevelRunner	Read	A 区进度条
意图提交	A2	Write	settle_batch（stop 亦经此——不直调 A3）
窗口选择	B1	Write	submit_window_selection(窗口位置序)
弃图刷新	A3	Write	request_refresh（挖掘期 Active 当场受理——D4 2026-09-12 上游已落稿；B1 refresh_board 编排承载）
节点推进	LevelRunner	Write	胜利 overlay「下一节点」
终局画面数据锚	B1 判定行（流水行协议）	Read	「终局判定行 = 胜负画面的数据锚」（B1 UI Requirements）；despawn 前状态可见性纪律 = entry 17③（销毁前捕获、载荷数据自包含、禁呈现层回读核心生命周期状态）；若需独立终局快照信号，须回 B1/实现期 ADR 补登记（B1 现无 settlement_snapshot 契约——2026-09-12 评审修正）

架构注记：UI 不拥有任何游戏状态——全部读经核心只读面，全部写经组合根（ADR-0001/0003）。呈现层信号载荷 schema 须在 D1 GDD 成文（entry 17①，缺项即 blocking）；场景级 headless 测试进 AC（entry 17②）；覆盖层层级断言（缺陷⑤——任何模态覆盖层必须有"打开时遮挡物隐藏"断言）。

更新触发注记（2026-09-12 评审增补——防实现层等待不存在的信号，entry 17 教训同类）：旗插/拔与移动成功反馈零事件外发（A2 发射面封闭）——经意图调用 ActionOutcome 返回值命令式驱动；AP/RAP 读数 A3 无推送信号——组合根每次调用返回后重查；状态效果 B3 纯被动容器零信号——状态栏刷新绑 B1 结算编排完成时点；库存 B4 query_inventory 查询面——写路径回执后重查。

---

Accessibility

项目尚未建 design/accessibility-requirements.md（gate-check 缺口，见 Open Questions）。本 spec 内建基线承诺：

• 对比：全部格底/面板底对数字墨 ≥4.5:1（WCAG AA）——art-bible §4.1 硬指标已可测（#33261B/#C9AF83 = 6.9:1 实测）；UI 数据一律墨族素面
• 色弱冗余：无任何信息仅靠色相承载——四格态靠完整/碎裂形+纹带形；奖励金 vs 危险红靠剪影+运动；UI 红/金强调对加图标+文案冗余；Boss 靠形状独占（art-bible §4.5 清单逐项成立）
• 灰度可辨：变异格纹带、四格态在灰度截图下可分类（art-bible §3.2 验收标准）
• 非色彩破坏性确认：弃图刷新（消耗 RAP 8 点）的确认交互与常规确认不同位（位置通道，色弱清单 #7）
• 字号下限：棋盘数字 ≥18px、明细带正文 ≥14px、tooltip ≥13px（1280×800 基座）
• 运动：无闪烁 >3次/秒；结算光带为方向性扫动非频闪；提供减动效选项（§Transitions）
• 键盘/Gamepad：MVP 纯鼠标可完成全部操作（technical-preferences 平台注记）；MVP 决策留痕：纯键盘导航/焦点序不做（2026-09-12——回合制点击驱动，平台仅承诺纯鼠标）；gamepad 导航序延后（Open Questions）

---

Localization Considerations

• 源语言中文（CJK）：运行时默认字体无 CJK 字形——CJK 字体随包为硬性前置（ADR-0003 已锁），实现 AC 覆盖
• 按钮文案单行约束：「停手」「弃图刷新」「跳过」「选用」——按钮宽度按 4 汉字上限设计；译为英文（"Hold"/"Reroll"/"Skip"）不超 1.6× 不破版；德语长词（"Aufgeben+Neu"类复合词）风险 HIGH——弃图刷新按钮允许两行或图标+缩写
• 明细带行文案：来源标注格式「{行为} {值} → {目标}（来源）」为模板插值，最长 token = 道具名（4 汉字）；行模板预留 40% 膨胀宽度（固定槽高 + clip 兜底）
• 数字格式：全部整数，无本地化格式需求；AP 点阵为图形载体不依赖文本
• 术语表锚定：旗/雷/停手/弃图刷新/轮次/结算 已在 GDD 体系内定名，译文须同步 registry terminology（五词条先例）

---

Acceptance Criteria

布局与可读

• 1280×800 与 16:9 全屏（canvas_items/expand）下五区无遮挡、无重叠、无内容裁切（棋盘 12×12 全部格子 + 数字完整可见）
• 进入战斗屏 ≤500ms 内可交互（棋盘 install 淡入完成后首格可点）；同屏 draw calls < 200（technical-preferences 预算）
• 四种格态（已开 0 格地板/已开雾格无字/未开格/未开雾格）灰度截图下一眼可辨（A2 D1×6②）
• 悬停光标区分移动/挖/旗三语义；可挖域（8 向相邻）常驻指示；非相邻格悬停显禁止反馈（A2 D1×6③）
• 已引爆雷格呈"可通行可读"（A2 D1×6④）
• 全部数字对所在格底对比 ≥4.5:1；明度恒定规则无违例（art-bible §4.1）

交互与反馈

• 挖/移/旗/停手/刷新全部操作纯鼠标可完成；stop 意图经 settle_batch 提交（代码走查 + 探针断言）
• 每次拒绝（棋盘面/资源面/相位）玩家可感知且两源可区分；voided（至少 stop 作废）可感知（A2 D1×6⑥、A3 双源）
• 道具窗口：usable_now=false 禁选+原因可见；至多选用 1 件；空库存不弹窗；选择传窗口位置非库存句柄（选中件库存态必变 Used——行为探针断言，缺陷④回归）
• 弃图刷新消耗 RAP 8 点、本轮上限 2 次可见（按钮文案实时「剩 N 次」；上限已随 A3 2026-09-12 修订生效）；RAP<8 资源面拒绝可见（EC13）；确认交互与常规确认不同位；换图后 AP 不重置、剩余次数扣减可见（上游已修订受理——2026-09-12 D4 落稿）
• battle_over 时 RAP 清零有可见反馈；level_clear 时库存清空有可见反馈（A3/B4 D1×⑤）
• battle_over 时状态槽全清有可见反馈（逐槽化光 + 微文案）（B3 D1×④）
• 敌人死亡瞬间可辨识（卡体灰化 + 碎裂退场，禁瞬消）；战斗段短路被掐灭的重击由行序可推断（B2 资产下限）

信息与归因

• 结算逐行明细实时可见、战斗后可回看完整流水（P2 逐行归因）；四类行（道具语境/奖励未生效/已消耗未生效/使用被拒）按 B4 D1×③ 呈现
• 敌人意图徽标挖掘期全程可见、映射全局恒定、含顺位与环长直觉编码（B2 D1×4①②③）
• 状态效果：极性呈现映射成文且非 magnitude 符号；空态渲染成文（裁决：槽隐藏）；满层溢出经明细行可见（B3 D1×①③④）
• 图例面板「迷雾 = 无雷盲区」条目恒在可随时回看；雾首遇提示一次性（每 run）且非模态不劫持输入，必含三要点（无雷盲区不赌命/雾格不传播连锁/雾内插旗纯损）（A4 D1×②）
• 零合法板（A1 EC5 降级）出现时玩家侧诚实提示（toast，非静默）
• 已开雾格与已开 0 格灰度截图下可判定区分（底色层 tint 残留——OQ8 裁决采纳）；雾区全开完成信号以视觉合并域为单元、无实例级双响（EC11；样张须含宽度 1 雾带两侧毗邻数字格等最坏用例——A4 AC-9）
• 效果行 value 为单次贡献值，不得与 pool_value（池合成值）相加呈现；零值伤害行可见不被吞；衰减行按聚合计数呈现（B1 呈现细则）
• 未生效类行（奖励未生效/已消耗未生效/使用被拒/溢出未生效）携带形状冗余（icon/划线），非色相独载
• 奖励徽章绘制优先级：旗之下、变异纹带之上、不进数字区；拾取瞬间 tier 档位可读（H1）

场景级测试（entry 17②③，缺项即 blocking）

• 场景级 headless 测试：真实实例化战斗屏场景 + 驱动完整对局 + 断言零脚本错误（ui_click_probe 模式扩展）
• 任何模态覆盖层（图例/明细回看/胜利/失败/窗口态）有「打开时遮挡物隐藏/输入锁定」场景级断言（缺陷⑤对照）
• 动态区全部固定槽高 + clip_contents——悬停文案换行不推挤布局（缺陷①回归）
• CJK 字体随包，全部中文文案渲染非豆腐块（ADR-0003）
• 敌人 despawn 后呈现层不回读核心生命周期状态（快照纪律，缺陷②回归）

---

Open Questions

1. Player journey map 未建——建议实现前补建（design/player-journey.md），校准挖掘→结算→终局情绪曲线与 art-bible §2 能量档的匹配
2. design/accessibility-requirements.md 未建（gate-check Pre-Production 缺口）——本 spec 内建 WCAG AA 基线承诺，正式分层（文本缩放/色盲模式/按键重映射）待该文档定稿
3. design/ux/interaction-patterns.md 未建——本 spec 新引入待入库 pattern：toast 双源拒绝、原位窗口激活、逐行兑现明细带、悬停预承诺光标、点阵资源显示（/ux-design patterns 批次入库）
4. 战斗表现美术测试（game-concept 已登记，B5 前强制）：本 spec 的常驻双舞台分屏（决策 D1）是测试的布局输入——敌人卡卡片式 vs 场景站桩式（无框立绘+底座）待样张定稿；本 spec 按"卡片式"起草（信息分层最稳），站桩式不改变分区结构
5. 移动动画形态（D3）：≤150ms 短滑为推荐值，playtest 观测「移动太瞬/太拖」反馈后调
6. 明细带挖掘期是否常驻上轮摘要：常驻（现方案）vs 结算后即收起——playtest 观测回看频率
7. 道具窗口原位激活（D2）：若 playtest 反馈窗口存在感不足（漏选），升级为 E 区放大 + 全屏微暗（仍非中央弹窗）
8. Gamepad 导航序：Partial 支持（非 MVP 门禁）——焦点环顺序待 gamepad 批次定
9. NodeOverlay / 关卡结算屏：相邻域屏，建议后续 spec design/ux/node-reward.md + design/ux/level-clear.md（本 spec 只锁出口锚点）
10. TunePanel 退役计划：正式侧归 C4（天赋树），切片调试入口在 D1 GDD 标注退役时点
11. 提示文案定稿：雾首遇三要点/chord 提示/空态文案归实现期文案 pass，本 spec 只锁必含要点与形态约束
12. 弃图刷新上游修订（已落稿 2026-09-12，布局决策 D4）：A3（Active 相位受理 + 每轮上限 2 次 + Waiting 代理退役 + 旧旗作废裁决 + 时间税失效预警）、A2（Active·仅刷新路径装板受理）、B1（stopped/ap_exhausted 恒 same_board + refresh_board 挖掘期刷新编排；AC-29 改写/AC-30 恒 same_board）、registry rap_rules 同步、systems-index 修订块登记。遗留观察项：当场刷新的节奏健康由 A3 OQ3 弃图率/刷新率预警承载，playtest 复核
13. D5 教学缺口挂靠（D5 GDD 未建，留痕）：挖到雷 = 敌方优势而非死亡（A2 D5「经典扫雷玩家最大预期违背」）、旗挡链（连锁止于旗属正常）、首次蓄力姿态一次性提示（B2）、窗口拾取→囤刀→选用闭环教学（B4）——本屏 toast 体系为落点候选，随 D5 批次定

---

§13 上游义务对照表（门禁核对用）

义务源	条目	本 spec 承载落点
A2 D1×6	① stop 经批次	§Interaction Map 停手行 + AC
A2 D1×6	② 四格态可辨	§Layout 格态 + AC
A2 D1×6	③ 悬停预承诺+可挖域+chord 提示	§Interaction Map + §States
A2 D1×6	④ 引爆雷格可通行可读	§AC
A2 D1×6	⑤ 路径预览裁决	决策 D3
A2 D1×6	⑥ 单意图帧+voided+拒绝可感知	§Interaction Map + §States 拒绝子态 + AC
A3	AP/RAP 常显+刷新入口+清零反馈+双源	§Layout C/D 区 + §Transitions + AC
A4×3	雾纹理/图例+首遇/已开雾格+tint	§States 雾图变体 + 图例组件 + AC
B1×3	①高光行强调呈现（标中旗金框行/清图 H2 金框行）②完美排雷呈现形态 ③EC5 零合法板提示/补偿/回退形态（toast 提示；补偿/回退不提供——三形态选型留痕 2026-09-12）	§States 高光/清图 + §States 拒绝子态 + §AC；注：结算明细屏+道具窗口 = B1 UX Flag 事项（本 spec 即其 /ux-design 产物），非 B1×3 台账
B2×4	意图映射/恒定/顺位/敌方池	§Component Inventory 敌人卡 + 意图线索映射目录（B2×4① 成文占位，资产定稿归 B5） + AC
B3×4	常显+空态/来源标注/溢出/去留	§States 空态 + §AC
B4×5	身份恒读/窗口/四类行/清图强调/清空反馈	§Component Inventory E 区 + §States 清图/高光 + AC
A1	EC5 零合法板诚实呈现（数据面经 B1×3③ 上抛）	§States 拒绝子态（toast）+ AC
B2 资产下限	受击反馈/死亡表现/顺位标记	§Transitions 受击 + §States 敌人死亡呈现（禁瞬消）+ §Component 顺位徽标；呈现语义在本 spec（同等 blocking），动画密度归 B5