19 KiB
19 KiB
需求卡片：卷轴视口批（关卡画面选路屏视口化）
- 来源：待办清单「超预算图策略升级路径——等比缩放与滚动视口两案待裁」条（状态＝文档设计已闭合＋待写卡，2026-11-05 用户裁滚动视口案落地）。
- 唯一事实源：level-map.md v2.0 §布局决策 5（行为四条表 ：101–104＋内嵌视口效果图 ：108–153＋像素级视觉判据 ：154）＋关卡节点图生成.md v1.5 §参数契约（图规模无呈现侧上限）。设计讨论四口子与效果图人审均 2026-11-05 用户裁决在案。
- 验收档：中（呈现交互面——玩家可见但不损持久状态；无存档写读、无结算公式、无 RNG 触碰；批卡 U0 时确认或改判）。
1. 目标与完成定义
关卡画面（选路屏）落卷轴视口范式：画布随图生长可超屏，屏为窗口——①视口锚点＝当前节点居中；②停点切换与兑付回图平滑滚动跟随（减动效瞬切）；③拖拽＋滚轮手动平移（clamp 画布包络、拖拽不触发选路）；④屏缘渐隐带＋平移提示 chip 指引。
完成定义：验证闸对照表 R1–R9 全部有绿读数；场景探针家族扩展件当轮真实跑批通过；代码域闸全绿；用户实机目检「深度 13 图拖拽可达首末列、推进跟随方向感」登记不阻塞。
2. 现状事实（开工自行复核）
- level_map_screen.gd:26-32 冻结公式常量：
LAYER_BASE_X=70／LAYER_STEP_X=122／SLOT_BASE_Y=52／SLOT_STEP_Y=58／NODE_ICON_PX=20.0／NODE_HALF(36.5,25)（52×36 的 1.4× 绘制）／HIT_PAD=6.0。 - level_map_screen.gd:66-69
_content_size(620,240)、_layout_cache——open_choices按图拟合画布尺寸。 - level_map_screen.gd:77-82 画布由
CenterContainer（PRESET_FULL_RECT）承载：整幅居中、无裁切无平移——超屏图（L3 层深 13，画布宽 1700.5px）两侧各 ~210px 出屏。 - level_gen_params.tres:41 L3
layers=13——深度 13 是现行定值，非极端情形。 - level_gen_params.gd:3-4、:69 头注「域校验沿关卡节点图生成.md v1.1 调参表已锁条款」「域并单点（关卡节点图生成.md v1.4 调参表）」——owner 文档已 v1.5 换代参数契约节，指针失效待反转（本卡 T4 随动）。
- ui_kit.gd:231-232
UiKit.motion(dur)呈现层 tween 时长单点包装（减动效面）。 - ui_struct_probe.gd:204
_audit("level_map", ...)既有结构审计锚；golden/README.md:8 level_map 全屏 golden＝历史留根、现行闸件未对拍（本批不触渲染闸对拍）。 - 全文件 662 行——超 code-conventions §1.1 的 ~400 行审视线，视口承载拆件有据。
3. 设计契约（违反＝L3 停机呈报）
- 🔴 冻结值零改动：节点图标 20px 烘焙 1:1、通道折线 2/3/4px、画布公式（宽=70+层深×122+44.5、高=52+槽位×58+25+24、下限 620×256）、节点方块 52×36×1.4 绘制、编号 10px——视口批只加行为，不动任何像素冻结件（level-map.md:69、:154）。
- 🔴 视口纯呈现态：平移位置零核心写、不进存档（重进本屏按锚点规则重新定位）；Core 层零触碰、RNG 零触碰（level-map.md:103 行、:107 视口为纯呈现态句）。
- 🔴 选路唯一通道：图上点击提交语义零改动；拖拽超阈值不得触发选路提交（level-map.md:103）。
- 🔴 零自动推进：视口跟随只随停点切换/兑付回图发生，不构成任何自动前进路径（level-map.md:141 零自动推进纪律不变）。
- 🔴 拆分边界纪律（code-conventions §1.1，2026-10-28 用户裁）：每个拆出单元有可陈述职责语句与单一变化原因；拆出单元有集体身份；「过阈值」只作发现信号；拆不出内聚单元＝停卡走豁免通道，禁硬拆凑绿。
- 🔴 禁为机检文本保留无效成员（code-conventions §1.1⑤）：机检键与卡片契约互斥＝停卡呈报，禁自造第三条路。
4. 范围边界
做：视口承载件、锚点跟随、平滑滚动、减动效瞬切、拖拽/滚轮平移、clamp、渐隐带与提示 chip、探针断言、schema 头注指针反转。 不做：缩放与缩略图（等比缩放案已否决）、其余视口暗示形态（边缘回弹等——布局决策 5 注后置）、顶栏/底栏/放弃按钮/覆盖层改动、生成器与参数表改动、键盘/手柄输入（排 Beta）。
5. 关联文档同步面
| 文档 | 关联点 | 同步义务 |
|---|---|---|
| level-map.md v2.0 | 布局决策 5 行为实现与 AC :260–271——实现若发现 spec 缺口 | 设计权威——实现批禁写，缺口逐条列反哺点清单由文档批落 |
| game/tests/README.md 能力清单 | 本卡新增能力行三行（写卡段已同批落表，见 §8 能力行列） | 机械面——实现批禁写；批末收尾核对表上名与落地一致（改名则回表） |
| level_gen_params.gd | 头注 ：3-4/:69 指针失效（owner 已 v1.5 参数契约） | 本卡 T4 随批反转指针（非行为改动——game/ 内实现批可写面） |
| 关卡节点图生成.md v1.5 | 无——本批实现不改变其任何陈述 | 无同步义务 |
6. 文件结构图（行为改动→对照表行互指）
| 文件 | 职责 | 改动性质 |
|---|---|---|
game/presentation/views/level_map_viewport.gd |
新增——卷轴视口承载件：画布宿主与裁切、平移状态与 clamp、锚点跟随、平滑滚动、指引件（拖拽/滚轮判定留画布 _gui_input——事件流同源） |
行为改动（R2–R8）·新增 |
game/presentation/views/level_map_screen.gd |
修改——CenterContainer 承载换视口件；停点切换/回图接线 reanchor()；_content_size 拟合后调 reanchor(false) 首锚 |
行为改动（R1＋R2/R3 随动）·复用既有文件 |
game/data/schemas/level_gen_params.gd |
修改——头注指针反转（owner 单点改为本文件域校验＋参数契约指针） | 非行为改动（R9）·复用既有文件 |
game/probe/level_map_viewport_probe.gd + .tscn |
新增——视口行为场景探针（真输入驱动） | 行为改动（R2–R8 验收载体）·新增 |
game/probe/probe_ui_util.gd |
修改——新增拖拽沿与滚轮沿真输入合成工具 push_drag_at／push_wheel_at（沿 push_click_at :717-733 同式；探针共用面唯一落点） |
非行为改动（探针侧工具）·复用既有文件 |
7. 任务卡 T0..T4
T0 读数与基线（0.5 工作日）
- 核对
tools/gdstyle_baseline.txt有无level_map_screen相关 S13 键；有则记录登记值（改后只降不升），无则记「无键、按工具默认」 - 跑场景探针现状读数：
…console.exe --headless --path . res://probe/ui_struct_probe.tscn（level_map 审计段绿）＋res://probe/screen_flow_probe.tscn——读数记入本步提交信息 - 跑冒烟
python tools/run_smoke.py——基线读数在案
T1 视口承载件与手动平移（1–1.5 工作日）
- 新增
level_map_viewport.gd（接口块见 §10）：setup(canvas, anchor_provider, viewport_size)、pan_by(delta)、viewport_center_canvas_pos() -> Vector2、is_clamped_at_edge() -> bool；clip_contents=true；成员 ≤8 level_map_screen.gd承载改造：CenterContainer 换视口件实例；open_choices拟合后调reanchor(false)首锚（入口停点锚入口组、其余锚当前节点——anchor_provider由 screen 提供画布坐标）- 拖拽/滚轮判定落画布既有
_gui_input（画布已持有鼠标事件流——悬停/选路同源，禁在视口件层做父子事件路由竞争；视口件只管裁切/offset/clamp/跟随）：拖动距离阈值（provisional 8px）判定，超阈值进拖拽态逐帧调viewport.pan_by()；滚轮横滚映射pan_by（代拍板：滚轮下＝向右/前进向） - clamp：
pan_by后 offset 收敛在画布包络内（viewport_center_canvas_pos()画布坐标恒在[half_view, canvas_size-half_view]夹紧域；画布小于视口＝居中分支——夹紧域退化为居中定位）；探针宿主沿 ui_struct_probe :204 同款（组合根真实屏main.ui.modals.run.level_screen），禁合成投喂替代真实路径 - 探针
level_map_viewport_probe.gd：断言 R3（拖拽移视口）、R4（滚轮移视口）、R5（clamp 边界）、R6（拖拽不触发选路——route_chosen零发射）；真实入口＝probe_ui_util 合成沿走push_input
T2 锚点跟随与平滑滚动（0.5–1 工作日）
reanchor(smooth)：目标 offset＝锚点画布坐标−视口半宽（居中）；smooth=true走单段缓动 tween 时长UiKit.motion(0.3)（provisional）；smooth=false即达；重入先杀在飞 tween 再建新（快速连续停点切换防叠加）- 减动效：
UiKit.motion通道既有减动效语义下滚动跳终态——探针断言 R7（减动效开＝位置即达，无 tween 中间帧） - level_map_screen.gd 停点切换与兑付回图路径接
reanchor(true)——入口停点锚入口节点组（多入口取组包围盒居中） - 探针断言 R2（停点切换后当前节点画布坐标投影＝视口中线 x=640±2）
T3 指引件（0.5 工作日）
- 视口件内渐隐带：屏缘左右各 70px 渐变（色取屏底同族——代拍板渐变 stops）；浅图画布不超屏时渐隐带隐藏（无暗示必要）
- 平移提示 chip：240×30 圆角 6、深底石灰描边、文案「◄ 拖拽画布 / 滚轮平移 ►」14px；图区底部居中（level-map.md:104）
- 探针断言 R8（渐隐带与 chip 可见性＋几何判据——像素级判据②③，level-map.md:154）
T4 指针反转与收口（0.5 工作日）
level_gen_params.gd头注 ：3-4/:69 反转：「取值域与字段契约单点＝本文件域校验；概念与设计意图＝关卡节点图生成.md v1.5 参数契约节」（非行为改动——grep 判据 R9）- 全探针最窄回归：ui_struct_probe level_map 段＋screen_flow_probe 复跑绿（波内修复只做出红最小单元的最窄确认）
- 产出物落位：
reports/iter<N>-实现报告-<日期>.md（各卡状态＋实机目检总清单＋实现决定记录）＋reports/iter<N>-反哺点-<日期>.md（同步面所列逐条落点）——轻闸全绿后、合并前写齐
估时合计：3–4.5 工作日（中值 3.5）。
8. 验证闸（改动—验收对照表）
| 需求点 | 改动（文件:行/行为） | 验收测试（名称＋落点＋尾缀） | 层级 | 真实入口 | 判据绑定面 | 能力行 |
|---|---|---|---|---|---|---|
| R1 浅图整幅居中无裁切＋画布入视口件承载（锚 design/gdd/ux/level-map.md:260） | level_map_screen.gd（CenterContainer→viewport 件） | level_map_viewport_probe.gd:_probe_shallow_no_crop〔卷轴批 V1〕 |
探针 | 场景探针实例化本屏＋open_choices 真实停点 | 画布尺寸≤视口时居中分支 offset 定位、无裁切 | 新增：关卡画面视口跟随 |
| R2 视口锚点：停点切换/回图后当前节点居中 x=640±2（锚 design/gdd/ux/level-map.md:101、:269） | level_map_viewport.gd reanchor＋screen 接线 |
level_map_viewport_probe.gd:_probe_follow_anchor〔卷轴批 V2〕 |
探针 | 合成推进停点切换经真实屏流程 | 当前节点画布坐标经 viewport_center_canvas_pos() 投影＝640±2 |
新增：关卡画面视口跟随 |
| R3 拖拽平移移动视口（锚 design/gdd/ux/level-map.md:103） | 画布 _gui_input（level_map_screen.gd）拖拽态调 pan_by |
level_map_viewport_probe.gd:_probe_drag_pan〔卷轴批 V3〕 |
探针 | ProbeUiUtil.push_drag_at 拖拽沿走 push_input |
_offset 位移量＝拖拽位移（clamp 前） |
新增：关卡画面视口平移 |
| R4 滚轮横滚移动视口（锚 design/gdd/ux/level-map.md:103） | 画布 _gui_input wheel 分支调 pan_by |
level_map_viewport_probe.gd:_probe_wheel_pan〔卷轴批 V4〕 |
探针 | ProbeUiUtil.push_wheel_at 合成滚轮沿走 push_input |
_offset 位移＝滚轮步进映射 |
新增：关卡画面视口平移 |
| R5 clamp 边界与首末列可达：不出露屏底空档、拖拽两极首列与末列（含 Boss）入屏（锚 design/gdd/ux/level-map.md:103、:260） | pan_by 收敛逻辑＋包络两极 |
level_map_viewport_probe.gd:_probe_clamp_bounds〔卷轴批 V5〕 |
探针 | 极端拖拽沿（超包络、两极到边） | viewport_center_canvas_pos() 恒在夹紧域；浅图居中分支；is_clamped_at_edge() 翻转；两极时深度 0 与深度 13 列中心入视口 |
新增：关卡画面视口平移 |
| R6 拖拽不触发选路提交（锚 design/gdd/ux/level-map.md:103） | 画布 _gui_input 阈值判定（provisional 8px） |
level_map_viewport_probe.gd:_probe_drag_no_submit〔卷轴批 V6〕 |
探针 | 拖拽沿起止于候选节点上方 | route_chosen 零发射＋屏幕未关 |
新增：关卡画面视口平移 |
| R7 平滑滚动与减动效瞬切（锚 design/gdd/ux/level-map.md:102、:188、:227） | UiKit.motion(0.3) tween／减动效跳终态 |
level_map_viewport_probe.gd:_probe_smooth_scroll_reduced_motion〔卷轴批 V7〕 |
探针 | 停点切换＋设置面减动效置位 | smooth=true 有 tween 中间帧；减动效开＝位置即达 | 新增：关卡画面视口跟随 |
| R8 指引件：渐隐带 70px＋chip 240×30 呈现（锚 design/gdd/ux/level-map.md:104、:154） | 视口件指引子件 | level_map_viewport_probe.gd:_probe_guidance_chrome〔卷轴批 V8〕 |
探针 | 深图 open_choices 真实停点 | 像素级判据②③（level-map.md:154）——可见性＋几何 | 新增：关卡画面视口指引 |
非行为改动行：schema 头注指针反转（level_gen_params.gd:3-4/:69）——判据＝全仓无「域并单点＝调参表」残留、头注含「参数契约节」指向（锚 design/gdd/systems/冒险循环/关卡节点图生成.md:109）；由 §6 文件结构图该行覆盖，T4 落步，实现报告对照表列非行为改动行。 锚行核对义务：开工时行号以当版文件为准（本卡锚基于 v2.0/v1.5 抄录）。
- 测试方式两分法：R1–R8 全走探针自动化（调试注入不适用——本卡零数据面改动，状态经真实停点与真实输入驱动）；用户目检项＝「深度 13 图拖拽可达首末列、跟随方向感、chip 不碍选路」登记进实现报告实机目检总清单（登记不阻塞）。
- 回归措辞：里程碑步（T 段）出口跑一次场景探针族全套；波内修复只做出红最小单元的最窄确认；新增探针先行孤立验证再并入全套。
- 测试削弱申报：无删旧断言申报；ui_struct_probe level_map 段既有审计判据不改——承载改造若触其结构断言面，适配性调整须在实现报告申报并保持判据语义。
- 独立验收审计：
reports/iter<N>-验收审计-<日期>.md，由未参与实现的会话执行；本卡验收档＝中，审计深度按 test-conventions §8.7 中档执行（对照表逐行全量、判据绑定面抽查、削弱检查逐处、直查例外逐条、最窄复跑以远端 CI 现查读数代证）。
9. 异常分级
- L1 自救：探针断言红→改后只跑出红探针的最小单元；闸红只跑红件。
- L2 记录继续：画布
_gui_input内拖拽态与悬停/选路命中分支次序的调整、渐变/chip 视觉微调（provisional 区间内）、S13 读数波动在只降不升约束内的消化。 - L3 停机写报告等用户：触碰 §3 任一 🔴；S13 键上升且无法只降；拆不出内聚单元；机检预算互斥＝上游缺陷停卡退回写卡段；拖拽误触选路提交且路由层面消不掉。
10. 落位与可复用性预检
- level_map_viewport.gd（新增）：不复用
ScrollContainer——其滚动条 UI、焦点/滚动语义与本屏「纯鼠标、无滚动条、锚点居中跟随」冲突，且平滑滚动与 clamp 语义仍需全自管；承载裁切用 Controlclip_contents（引擎内建，项目已有 clip 先例）。唯一面：视口 offset 状态只落本件（screen 的_layout_cache仍管布局、不管视口）；全仓 grep 无第二处视口/平移逻辑。分层：呈现层内部子件——构造注入（canvas/anchor_provider/viewport_size 一次交齐，code-conventions §1.6 拆分交接）；读核心只读面经 screen 既有出口，零新增核心触点。 - probe_ui_util.gd 增补（复用既有文件）：
push_drag_at／push_wheel_at落探针共用面唯一落点——禁另起工具文件散落；push_click_at（ui_input_probe :717-733 同式）点击沿同式扩展。 - 指引件（渐隐带/chip）：随视口件承载（同职责：视口呈现行为）；不立独立文件——拆出「命不出名字的打包」即凑计数袋。
- level_gen_params.gd 头注反转（复用既有文件）：注释单行改动，无新增件。
11. 实现规范预算
- 新增 level_map_viewport.gd 三查：①接口块公开方法 4（setup/pan_by/viewport_center_canvas_pos/is_clamped_at_edge）≤20 ✓；②成员变量 ≤8（_canvas/_anchor_provider/_viewport_size/_offset/_tween/_drag_active/_drag_accum/_guided_visible）≤15 ✓；③无迁移函数（新件零存量函数迁入——screen 侧只是接线改造，hover/命中逻辑零迁移）。
- 存量触面：level_map_screen.gd——T0 记 S13 键基线；本批改动为承载替换与 reanchor 接线，预期键值持平或只降；达成手段＝T4 复跑 S13 对账。
- 指标例外：无申报。
12. 代拍板白名单
- 画布
_gui_input内拖拽态与悬停/选路命中的事件分支次序（红线＝R6 判据不破）。 - 拖拽距离阈值具体值（8px 附近 provisional 区间内定值）。
- 平滑滚动缓动曲线类型（单段缓动家族内选型）。
- 渐隐带渐变 stops 与 chip 深底/描边色值（art-bible §4.1 冻结色板同族取值）。
- 滚轮方向映射（下＝向右/前进向）。 超清单决定记入实现报告「实现决定记录」节。
13. 待裁点
零待裁点，开工门＝U0（四口子与效果图 2026-11-05 用户已裁决；验收档「中」随批卡确认）。