gplan-2/reports/需求卡片-封印印记法阵化批-2026-11-04.md

需求卡片：封印印记法阵化批（2026-11-04）

来源：待办清单「棋盘封印印记图形换代——现件仍是扫雷旗形，改法阵或锁链待设计」条目（唯一事实源：design/art/art-bible.md v3.41 §3.2「封印印记」条＋§8.2「封印印记参数表」；设计闭合凭据＝art-bible v3.41 落文＋2026-11-04 用户点头 82% 档样张）。验收档：中（纯呈现层——零持久状态、零 RNG、零数值；做错的后果=棋盘观感错，玩家可见但不损存档）。状态：已写卡（v1.0，2026-11-04）。改动面：游戏代码（含随逻辑改的测试代码）。

1. 目标与完成定义

这批做什么：把棋盘侧封印印记从「32×32 贴图铺满整格」改为「着色器按格边参数化绘制」——环＋十字＋环外一圈压暗光，环径 82% 格宽，随格边 26–46px 连续缩放；贴图件仅战末金蜡封徽记继续使用。

面	现状	终态
绘制手段	draw_texture_rect(tex_seal, rect) 铺满整格（28 格缩 0.875、46 格放 1.4375，均非整数）	着色器按格边实时画（无缩放、任意格边清晰）
形	环＋十字（32px 贴图）	环＋十字（参数化：环径 82% 格宽／壁厚 11% 环径／臂宽 15.6% 环径）
底光	无	环外一圈压暗光（宽 9% 格边、峰值 α0.50、衰减 1.6、不出格）
贴图	棋盘与战末蜡封共用 seal_mark.png	棋盘侧不再引用；蜡封继续用该贴图（battle_end_overlay.gd:84）

什么状态算完：五枚参数常量落 ui_kit 且有单元断言守门；着色器与层件落码并被 CellUnit 按格挂载；棋盘侧贴图引用路径全部退役且全仓零残留；三关渲染取证帧量出环径 82%±1px、光圈不越格边；迷雾态隐藏与小人层级两条不断；既有套件零转红；代码域闸全绿；reports/ 三份产出物写齐。

2. 设计事实源

• 唯一事实源：design/art/art-bible.md v3.41 §3.2「封印印记」条（形／画法／光圈／层序纪律）＋ §8.2「封印印记参数表」（五枚定值＋衰减＋参数单点声明）。
• 格边口径：design/gdd/ux/battle.md:137-143「棋盘格尺寸公式」——clampi(..., 26, 46)，基座档 14×14＝28px、小板最大 46px。
• 该文件与待办清单条目状态里的闭合凭据一致（美术设计已闭合＝art-bible v3.41＋样张过审）；T1 首步复核两者一致，冲突即 L3 停卡。

3. 现状事实（2026-11-04 worktree seal-shader 实查，基点 7b5308c1，开工自行复核）

• game/presentation/views/board_view.gd:539-541 封印槽维护——u.face.tex_seal = _palette.seal_tex if (seal and not revealed and _palette.seal_tex != null) else null；:542-545 移除格清槽；:70 var _cell := 46.0；:582 缺图回落 glyph = "封"。
• game/presentation/views/cell_mark_overlay.gd:33 var tex_seal: Texture2D；:95-96 canvas.draw_texture_rect(tex_seal, rect, false)——整格铺满，非整数缩放根源在此。
• game/presentation/views/tile_palette.gd:19 const TILE_SEAL_MARK := "res://assets/art/board/seal_mark.png"；:111 seal_tex = UiKit.load_tex(TILE_SEAL_MARK)。
• game/presentation/views/board_cell_unit.gd:10 preload 微光层件；:46 var _glow_layer；:58-63 _draw 六步时序（_draw_fog_layer 在 :69，退色层在 :64 之后）；:90-100 _sync_glow_layer() 是子件生命周期样板。
• game/presentation/views/cell_type_glow_layer.gd 全件——子件模板：材质独占、draw_rect 全幅、Color(1,1,1,1.0/255.0) 非零 alpha 触发着色器、参数全取 ui_kit。
• game/presentation/views/ui_kit.gd:33 SEAL_BLACK；:90-93 TYPE_GLOW_ALPHA/BAND_FRAC/SOFT/CORNER（参数单点先例）。
• 取证面：tools/render_gate.sh:107-114 已挂 board_shot_probe L1–L3 棋盘抓帧；game/probe/type_glow_shot_probe.gd 是同类「单要素呈现」取证先例。
• game/presentation/views/battle_end_overlay.gd:84 战末金蜡封印记直接读 res://assets/art/board/seal_mark.png（不走 tile_palette 常量）——本批不动它。

4. 设计契约（违反即返工红线）

• 🔴 参数五值：环外径 0.82×格边、壁厚 0.11×环径、臂宽 0.156×环径、光圈宽 0.09×格边、光圈峰值 alpha 0.50、衰减指数 1.6；单点=ui_kit.gd 五枚常量，着色器只读注入，代码内禁第二处字面值。
• 🔴 光圈不出格：着色器内半径上限夹到 cell_px/2，禁越界到邻格。
• 🔴 色只用一枚：印记与光圈都取 SEAL_BLACK（光圈只改 alpha）；禁新增色、禁 ui_kit 之外裸 Color8（既有守卫）。
• 🔴 层序：印记层挂 CellUnit 之下（低于 BoardView 层的小人精灵），且 fog_state != 0（区外全黑／记忆态）时整层隐藏——§6.5「封印随格隐没」。
• 🔴 禁动效：不呼吸、不脉冲（§2.1 挖掘期唯一在动＝接触带微光）。
• 🔴 贴图退役面：棋盘侧三处引用（tile_palette.gd:19/:111、cell_mark_overlay.gd:33/:95-96、board_view.gd:539-541/:582）全部退役后，game/ 内 seal_mark 只剩 battle_end_overlay.gd:84 一处引用，链上禁留旧常量别名或死槽。
• 🔴 测试纪律：禁变异类测试、禁撤销类取证、禁删断言换绿（第 8 节申报之外零删改）。

5. 范围边界

收件：着色器文件、层件、CellUnit 挂载与生命周期、BoardView 下发、棋盘侧贴图三处退役、五枚常量、参数与雾门控断言、三关渲染取证。

不收件（去向已指认）：

• 施印瞬间特效（清单 §4 两件中的第一件）——未实装，另立演出类条目时再做；本批只做常显形态。
• 战末金蜡封徽记形制——继续用现有贴图，零改动。
• 色板、其它格面元素（数字／徽章／变异纹带／类型微光）——零触碰。
• game/tests/README.md 能力行——新增一行「棋盘封印印记呈现（参数化绘制）」（写卡段已随卡落，代表用例 seal_mark_params_test.gd 两函数；实现批禁写该文件）。
• 数值表、MC、模拟——零跑（零数值改动）。

6. 关联文档同步面

实现批禁写 design/ 与根规则文件；下表每条落文义务进 reports/iter<N>-反哺点-<日期>.md，由用户裁决后归文档批落文：

文档	关联点（本批实现会改变它的哪条陈述）	同步义务（反哺点清单逐条承载）
design/art/art-bible.md §3.2／§8.2	已随美术设计闭合批落文（v3.41，条款即本批规格）	实现期只核不改；若要改值＝文档批，不在实现批
体验验证清单.md 第 4 条	判据现为「seal_mark.png 三关加载、非字形回退」，贴图退役后该判据失去对象	反哺点列改判据：「三关封印格呈环＋十字、环径 82%±1px」
design/art/asset-path-map.md	seal_mark.png 用途由「棋盘封印印记」改为「战末蜡封徽记专用」	反哺点列行号与改后表述
game/tests/README.md	能力行已由写卡段新增「棋盘封印印记呈现（参数化绘制）」一行	批末核对代表用例名与实现落地函数逐字一致（不一致则反哺点提出）
术语表	零新增术语（环／十字／光圈均为现有词或本次条款已释义）	确认行「零新增术语」

（机检口径：本表同步义务格无一条写「随批」。）

7. 任务卡 T1..T6

卡前·文件结构图

新增
  game/presentation/views/seal_mark.gdshader        【行为改动 R1/R2/R3】环＋十字＋环外光圈，参数只读注入
  game/presentation/views/seal_mark_layer.gd        【行为改动 R1/R3/R4】子件承载（仿 cell_type_glow_layer）
  game/tests/unit/presentation/seal_mark_params_test.gd 【非行为·新增】五常量与注入面断言
改动
  game/presentation/views/ui_kit.gd                 【非行为 R1】+五常量（值同 art-bible §8.2）
  game/presentation/views/board_cell_unit.gd        【行为改动 R1/R4/R5】+封印子件挂载/生命周期/雾门控/edge 联动
  game/presentation/views/board_view.gd             【行为改动 R4】:539-541 槽位维护改下发封印层；:582 回退分支退役
  game/presentation/views/cell_mark_overlay.gd      【行为改动 R6】删 tex_seal 成员与 :95-96 绘制、头注改写
  game/presentation/views/tile_palette.gd           【行为改动 R6】删 TILE_SEAL_MARK 与 seal_tex
  game/tests/run_all.gd                             【非行为】注册新单元件
  game/probe/board_shot_probe.gd 或新增探针        【行为改动 R1/R3/R5】三关封印格取证帧
不动
  game/presentation/views/battle_end_overlay.gd:84  战末蜡封继续读同一张 PNG
  game/assets/art/board/seal_mark.png               素材在库保留（蜡封专用）

T1 常量与参数断言（估时 0.25 工作日；区间 0.25–0.5）

取用：无。产出：UiKit.SEAL_RING_FRAC/SEAL_WALL_FRAC/SEAL_ARM_FRAC/SEAL_HALO_ALPHA/SEAL_HALO_GAMMA（float 常量）＋seal_mark_params_test.gd。

• 复核 art-bible v3.41 §8.2 参数表与本卡第 4 节五值逐字一致（不一致＝L3 停卡）
• ui_kit.gd 邻近 SEAL_BLACK(:33) 处新增五常量，值 = 0.82 / 0.11 / 0.156 / 0.50 / 1.6，各带一行来源注（引 §8.2）
• 新增 tests/unit/presentation/seal_mark_params_test.gd：断言五常量取值；断言 seal_mark.gdshader 文件存在且文本含 cell_px/ring_frac/wall_frac/arm_frac/halo_frac/halo_alpha/halo_gamma/mark_col 七个 uniform 名
• tests/run_all.gd 注册该件（仿既有 {"path": ..., "expect": 0} 行）

T2 着色器本体（估时 1.0 工作日；区间 0.75–1.5）

取用：T1 五常量。产出：seal_mark.gdshader（shader_type canvas_item），uniform 名单见 T1。

• 写 seal_mark.gdshader：以格中心为原点算半径 r；环体 = ring_r-wall/2 ≤ r ≤ ring_r（ring_r = 0.5*cell_px*ring_frac，wall = 0.11*2*ring_r）；十字 = (|dx| < arm/2 或 |dy| < arm/2) 且 r < ring_r（arm = arm_frac*2*ring_r）；光圈 = r > ring_r 区间按 (1 - t)^halo_gamma * halo_alpha 混黑，t = (r-ring_r)/halo_w，halo_w = 0.5*cell_px*halo_frac，并夹 r ≤ 0.5*cell_px
• 隔离验证：最小场景（单 32px/46px/28px 三个方块）直跑抓帧，确认三档格边下环径比例一致、光圈不越格（截图落 artwork/ 在途目录，不入 git）
• 参数默认值仅作兜底（与 §8.2 同值），实际由 gd 侧逐次注入；代码内注释写明「禁在此改值」

T3 层件与接入（估时 1.0 工作日；区间 0.75–1.5）

取用：T1 常量、T2 着色器。产出：seal_mark_layer.gd＋BoardCellUnit 挂载接口。

• 新增 seal_mark_layer.gd：extends Node2D；setup(edge: float, on: bool) -> void 内建 ShaderMaterial 并注入七参数（mark_col = UiKit.SEAL_BLACK）；_draw() 用 draw_rect(Rect2(Vector2.ZERO, Vector2(edge, edge)), Color(1,1,1,1.0/255.0))（同微光层非零 alpha 手法）
• board_cell_unit.gd：const _SEAL_LAYER := preload(...)；var _seal_layer: Node2D；func _sync_seal_layer() -> void（on 才建、off 撤、edge 变更重注入）；edge setter 与 fog_state setter 各追加一行联动
• board_view.gd:539-541 改为写 CellUnit 的新公开属性 seal_on: bool（替代 u.face.tex_seal 赋值），:542-545 移除格同置 false
• 断言：单元件内新增 _test_fog_gate——造 CellUnit、置 seal_on = true、置 fog_state = 1 → 断言封印子件不可见；fog_state = 0 → 可见

T4 棋盘侧贴图路径退役（估时 0.5 工作日；区间 0.25–0.75）

取用：T3 接入完成（封印不再依赖贴图）。产出：三处引用清零。

• cell_mark_overlay.gd：删 :33 tex_seal 成员与其 setter、删 :95-96 绘制块、头注「④ 封印」段改写为「封印由 seal_mark_layer 子件绘制」
• tile_palette.gd：删 :19 TILE_SEAL_MARK 与 :111 seal_tex 赋载；确认无第二消费者（grep -rn "TILE_SEAL_MARK\|seal_tex" game/）
• board_view.gd：删 :539-541 槽位维护语句与 :582 缺图回退分支，注释改写；确认 battle_end_overlay.gd:84 仍以字面路径读图（不受影响）
• 全仓 sweep：grep -rn "seal_mark" game/ --include=*.gd 只余 battle_end_overlay.gd:84 一处；把该 grep 结果写进实现报告作结构性证据

T5 渲染取证与回归（估时 0.75 工作日；区间 0.5–1.0）

取用：T3/T4 完成态。产出：三关封印格取证帧与读数表。

• 在 board_shot_probe.gd 增「封印格抓帧」分支（或新增 seal_mark_shot_probe）：每关放一枚封印后抓整板帧，落盘带关名标签
• 读数脚本（放 tools/ 或探针内直算）：从帧里量环外径像素 ÷ 格边长，输出三关读数
• 判据落读数表：环径落 82%±1px；光圈外缘不超过格边（邻格边缘亮度与无封印帧一致）
• 回归：既有冒烟／单元／探针／渲染套件零转红（改前改后各一次，记录读数）

T6 产出物落位（估时 0.25 工作日；区间 0.25–0.5）

• reports/iter<N>-实现报告-<日期>.md：各卡状态＋实机目检总清单（三关封印格观感、蜡封观感、封印格与变异纹带同格观感）＋变异验证记录表（T1–T5 各条：变异点 file:行、跑的闸、红输出、还原结论）＋遗留读数义务
• reports/iter<N>-反哺点-<日期>.md：第 6 节四条同步面逐条落（体验验证清单第 4 条改判据、asset-path-map 用途改述、能力清单零新增确认、术语零新增确认）
• reports/iter<N>-代拍板-<日期>.md：按第 10 节白名单记录，全按卡执行则写「零拍板」
• 轻闸全绿后、合并前复核三份齐备

估时汇总：0.25＋1.0＋1.0＋0.5＋0.75＋0.25＝3.75 工作日（区间 2.75–5.75）。低于 5 个工作日冻结线——编入迭代时按冻结制处理（凑批后转待开工）。

8. 验证闸（改动—验收对照表）

#	需求点	改动（文件:行/行为）	验收测试（名称＋落点＋尾缀）	层级	真实入口	判据绑定面	能力行
R1	环径 = 82% 格边，随格边连续	seal_mark.gdshader（ring_frac 算环半径）＋ui_kit.gd 五常量	seal_mark_params_test.gd:_test_param_values（unit/presentation，尾缀 _test）＋T5 三关帧量读数	单元＋探针	BoardCellUnit.edge → 层件 setup() → ShaderMaterial 参数	常量值逐项相等；三关帧读数「环外径像素 ÷ 格边」落 0.82±0.01	新增：棋盘封印印记呈现
R2	壁厚 11% 环径、臂宽 15.6% 环径	同上 shader	seal_mark_params_test.gd:_test_shape_ratios＋T5 帧量	单元＋探针	同 R1	两常量逐值相等；帧上「环壁像素宽 ÷ 环外径」落 0.11±0.02	新增：棋盘封印印记呈现
R3	光圈只在环外、不出格	shader halo_frac 与 r ≤ cell/2 夹取	seal_mark_params_test.gd:_test_halo_clamp_present＋T5 邻格边缘亮度比对	单元＋探针	同 R1	shader 文本含夹取行；封印帧邻格边缘亮度与无封印帧差 ≤1/255	新增：棋盘封印印记呈现
R4	迷雾态隐藏	board_cell_unit.gd fog_state setter 联动	seal_mark_params_test.gd:_test_fog_gate	单元	BoardCellUnit.fog_state 属性写入面	fog_state=1 时封印子件 visible == false；=0 时 true	新增：棋盘封印印记呈现
R5	印记在小人之下	子件挂 CellUnit（BoardView 层 hero 精灵天然在上）	T5 帧取证	探针	board_view._place_hero	小人格中心像素 = 小人体色（非封印黑）	新增：棋盘封印印记呈现
R6	蜡封仍用贴图	battle_end_overlay.gd:84 不动	既有战末弹层探针/单元零转红＋grep sweep	单元＋sweep	战末结算弹层构建	grep -rn "seal_mark" game/ --include=*.gd 命中数 = 1	新增：棋盘封印印记呈现
R7	零新增色	shader 只用 SEAL_BLACK＋alpha	seal_mark_params_test.gd:_test_single_color＋渲染闸有效色数	单元＋闸	材质注入点	shader 文本零 Color8 且无第二色常量；该屏有效色数不超既有读数	新增：棋盘封印印记呈现

测试削弱申报：本批不删改任何既有断言。board_view.gd:582 的缺图回退分支是行为退役（回退对象消失），不属「删断言」。

9. 异常分级

• L1 自救：着色器编译报错、参数注入拼写错、探针抓帧目录缺失——就地修，重跑最小单元。
• L2 记录继续：取证帧读数轻微偏离（≤2px）且目检无感——记入实现报告「读数偏差」节，继续推进。
• L3 停机呈报：参数与本卡第 4 节冲突、layer 挂载位置被迫改动、贴图退役引发图外消费者（白名单外）、渲染闸对新增着色器报红且无法定性。

10. 代拍板白名单

1. 常量与 uniform 的命名拼写（须含 SEAL_ 前缀）、注释措辞。
2. 探针文件名与抓帧文件命名（T5）。
3. commit 拆分粒度与提交信息措辞。
4. 单元件内断言函数命名与内部辅助函数拆分。
5. 隔离验证用的最小场景形态（方块数、摆放）。

超清单必呈报：任何参数取值改动、层挂载层级改动、贴图退役范围扩大（例如顺手删 seal_mark.png）、动 battle_end_overlay、动其它格面元素。

11. 待裁点

零待裁点。开工门=U0（用户指定迭代号发令）。设计权归用户；本卡内所有取值均来自 art-bible v3.41 §8.2，实现期禁自改。

12. 落位与可复用性预检

新增件	复用面（盘上是否已有同类）	唯一面	分层与交互
seal_mark.gdshader	复用 cell_type_glow.gdshader 的 canvas_item＋距离场写法与「参数全由 gd 注入」纪律；不新建框架	只此一件承担封印图形；不与微光着色器合并（两者生命周期与挂载面不同：微光按组、封印按格态）	presentation 层；无 core 依赖；不读写存档/RNG
seal_mark_layer.gd	复用 cell_type_glow_layer.gd 的子件模式（材质独占、全幅 draw_rect、非零 alpha 触发）；不复制其函数体	只此一件承载封印子件；微光层件零改动	挂 BoardCellUnit 之下；受 edge／seal_on／fog_state 三输入驱动
五枚常量	复用 ui_kit.gd 既有常量区与 TYPE_GLOW_* 命名先例	全仓唯一定义点，着色器只读注入；代码内禁第二处字面值	参数单点，与 art-bible §8.2 对照
seal_mark_params_test.gd	复用 tests/unit/presentation/ 目录约定与 run_all.gd 注册表	只此一件守封印参数与门控	单元层，不触渲染

无新增 core 件、无新增数据表、无新增场景；game/tests/README.md 判定零新增（理由见第 5 节）。

13. 独立验收审计

• 入口：reports/iter<N>-验收审计-<日期>.md；由未参与实现的会话或子代理执行（test-conventions §9.7）。
• 审计面：第 8 节七行逐行核「真实入口是否绕过改动点」＋代码域闸真跑回执＋第 5 节退役面 sweep 结果。
• 未过不得合并；审计结论进实现报告收尾节。