diff --git a/AGENTS.md b/AGENTS.md index 36259288..e32a5bf6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -16,21 +16,22 @@ ## 运行与验证（工作目录 = 含 project.godot 的切片目录） -- **合回验证 = 前置检查 ＋ 远端 CI（前置检查 2026-11-06 用户裁）**：主区 `git merge --no-ff` 落合并提交前，pre-merge-commit 钩子（`tools/hooks/pre-merge-commit`）自动跑 `tools/run_all_gates.sh --premerge`——冒烟测试＋单元与集成测试全套件（4 分片），热导入缓存约 2 分钟；红＝合并提交不落（修红后 git commit 续合，或 git merge --abort 放弃），快进合并不触发钩子，`--no-verify` 可跳过且仅属用户。git merge 合回 master 落地后，post-merge 钩子（`tools/hooks/post-merge`）自动 `git push origin master` 触发远端 CI（Gitea Actions，runner＝Mac 本机 host 模式，环境自举件＝`tools/ci/mac_setup.sh`），工作流（`.gitea/workflows/ci.yml`）按改动域分流（分流算法单点＝`tools/ci/domain_route.sh`）：游戏码批＝两域全量含渲染闸，文档批＝文档域秒级闸，纯闸件/管线批＝零触发。远端结果**按需现查**：`tools/ci_check.sh <合并提交>` 读该提交任务的 run `status`/`conclusion`，只呈报、不落盘（2026-11-04 用户裁：合回不等待、不唤醒；判据＝run 落定后的终局态，且绿须坐实跑闸步真跑过——零触发批呈报「未验」不作绿证，细则=process-conventions §1 第 3 条）。**合回落地即向用户呈报本批总结并止回合**，禁前台 sleep／轮询等 CI。CI 红态不回滚合并——红项在案、修复批合回即再推再验追绿；开工先跑现查件读 CI 状态，红未修不开新批。同一份字节禁止第二次人手跑。`tools/run_all_gates.sh` 仍是全部验证闸的**唯一入口与唯一清单，域划分与选闸算法只写在它这一个地方**，文档禁另列清单；`--code`／`--docs`／`--quick` 是开发期改完即测的选档入口（细则见 process-conventions §4），全量档不替代它。**runner 依赖**：Mac 需开机在线（关机＝远端任务排队延后）；换机/重装按 `tools/ci/mac_setup.sh` 自举 -- 单件直跑（＝改完即测的最窄确认，其读数就是那一步的凭据；跨改动面的漏网由合回后远端全量档兜）：冒烟测试 `python tools/run_smoke.py`（`game/tests/smoke_boot.tscn` 极小启动场景）· 系统测试 `python tools/run_system_test.py`（宿主 `game/tests/system_test.gd`）· 场景探针 `…console.exe --headless --path . res://probe/ui_probe.tscn` · 单元与集成 `… --script res://tests/run_all.gd` +- **合回验证 = 前置检查 ＋ 远端 CI（前置检查 2026-11-06 用户裁）**：主区 `git merge --no-ff` 落合并提交前，pre-merge-commit 钩子（`tools/hooks/pre-merge-commit`）自动跑 `tools/run_all_gates.sh --premerge`——冒烟测试＋单元测试全套件（4 分片），热导入缓存约 2 分钟；红＝合并提交不落（修红后 git commit 续合，或 git merge --abort 放弃），快进合并不触发钩子，`--no-verify` 可跳过且仅属用户。git merge 合回 master 落地后，post-merge 钩子（`tools/hooks/post-merge`）自动 `git push origin master` 触发远端 CI（Gitea Actions，runner＝Mac 本机 host 模式，环境自举件＝`tools/ci/mac_setup.sh`），工作流（`.gitea/workflows/ci.yml`）按改动域分流（分流算法单点＝`tools/ci/domain_route.sh`）：游戏码批＝两域全量含渲染闸，文档批＝文档域秒级闸，纯闸件/管线批＝零触发。远端结果**按需现查**：`tools/ci_check.sh <合并提交>` 读该提交任务的 run `status`/`conclusion`，只呈报、不落盘（2026-11-04 用户裁：合回不等待、不唤醒；判据＝run 落定后的终局态，且绿须坐实跑闸步真跑过——零触发批呈报「未验」不作绿证，细则=process-conventions §1 第 3 条）。**合回落地即向用户呈报本批总结并止回合**，禁前台 sleep／轮询等 CI。CI 红态不回滚合并——红项在案、修复批合回即再推再验追绿；开工先跑现查件读 CI 状态，红未修不开新批。同一份字节禁止第二次人手跑。`tools/run_all_gates.sh` 仍是全部验证闸的**唯一入口与唯一清单，域划分与选闸算法只写在它这一个地方**，文档禁另列清单；`--code`／`--docs`／`--quick` 是开发期改完即测的选档入口（细则见 process-conventions §4），全量档不替代它。**runner 依赖**：Mac 需开机在线（关机＝远端任务排队延后）；换机/重装按 `tools/ci/mac_setup.sh` 自举 +- 单件直跑（＝改完即测的最窄确认，其读数就是那一步的凭据；跨改动面的漏网由合回后远端全量档兜）：冒烟测试 `python tools/run_smoke.py`（`game/tests/smoke_boot.tscn` 极小启动场景）· 系统测试 `python tools/run_system_test.py`（宿主 `game/tests/system_test.gd`）· 场景探针 `…console.exe --headless --path . res://probe/ui_probe.tscn` · 单元测试 `… --script res://tests/run_all.gd` - 调参批量：`--script res://sim/adventure_monte_carlo.gd`（全冒险期望）· `res://sim/reward_expectation.gd`（奖励期望）；关卡完成率/难度类测量一律走全冒险 - 数值验证：`python tools/balance_verifier.py`（采集端 `res://sim/verifier_batch.gd`，报告与原始数据落 `sim-data/`） - 熵增闸（新类别 = 同批修订 Project Layout + 白名单）：`python tools/repo_structure_audit.py` ## Project Layout -- `design/gdd/` — 现行设计文档树（根索引 `02-系统清单.md`，文档增删必须同步；`gdd/ux/` 战斗画面与交互规格） +- `design/gdd/` — 系统与概念文档树（根索引 `02-系统清单.md`，文档增删必须同步） +- `design/ux/` — 呈现实现设计规格层（屏级布局、交互规格与预览图；与 gdd/ 同级） - `design/art/` — 美术文档（圣经/角色设计/两份清单/路径图/提示词库与生图操作单）；只放 .md 与 `references/` 参考图，审计报告与调研归 `reports/` - `design/engineering/` — 工程规范（五份规约 + architecture + engine-reference） - `design/content-archive/` — 退役内容留底（活文档，2026-10-20 用户裁新立：内容已退役、留底供日后重新过准入；落内文件头部写明所属线） - `design/research/` **已退役（2026-10-21 用户裁）**——`design/` 全目录只放持久化设计文档与规范，调研/提案/评估/历史验收一律落 `reports/`（熵增闸退役路径清单已收该目录，再现即判红）；`design/qa/` 已退役，验证截图不进 `design/`（判据见 doc-conventions §11） - `artwork/` — 在途图像素材唯一工作区（文档归文档/在途图归一处/终稿归游戏）；整目录不入 git（.gitignore 强制），收口归档 `archive/` -- `game/assets/art/` — 已验收终稿（入包被游戏加载）；`game/probe/` — 场景探针的场景与宿主＋探针共用面（probe_gate/render_gate 在闸＋人工取证探针）；`game/sim/` — 测量/诊断/模拟驱动件（autoplay 策略、MC 批量、数值验证采集端）；`game/` — 游戏工程本体（代码 + tests/ 冒烟/单元/集成/系统测试面） +- `game/assets/art/` — 已验收终稿（入包被游戏加载）；`game/probe/` — 场景探针的场景与宿主＋探针共用面（probe_gate/render_gate 在闸＋人工取证探针）；`game/sim/` — 测量/诊断/模拟驱动件（autoplay 策略、MC 批量、数值验证采集端）；`game/` — 游戏工程本体（代码 + tests/ 冒烟/单元/系统测试面） - `sim-data/` — 机器读数据产物；数据件不入 git（入库例外 = README+analyze.py+growth_model.py）；MC 锚与读数常驻留盘，无数值调整禁重跑 - `tools/` — python 工具脚本（含 `hooks/`＝版本化 git 钩子，经 `core.hooksPath` 挂载）；`archive/` — 批次完结归档 zip（gitignored） - `reports/` — 过程件容器：**需求卡片**（写卡段产出，实现批的输入合同）＋迭代批产出物（实现报告/GDD 反哺点清单）＋设计讨论段过程稿（提案/审计/需求澄清/评估）；**实现批唯一可写目录**，中间文档唯一容器（`design/research/` 已退役），不是事实源（细则见 `reports/README.md`） @@ -59,7 +60,7 @@ 2. **判断挂依据**：判断＝「X 是／不是／造成了／应该」类陈述；每个判断后面必须跟依据。依据只认三种：仓库文件＋行号或逐字引用（给行号就必须真读过那几行）；本对话的消息号或原话；外部链接。三种都拿不出的判断必须当场标「这是推测」；说不出依据就答「不知道／没查过」，禁止编造。答复形状＝结论行→依据清单→细节。 3. **简洁**：同一意思只说一遍；能用一句不说两句。硬约束、数字、前提条件不参与压缩；信息完整与简洁冲突时保信息。 4. **多角度**：介绍一个物体、一个概念、一个问题，多角度讲清楚；每角度信息点 ≤3 个，禁止违背第 3 条。 -5. **闸况呈报用闸名**：对话里报验证闸的跑批结果一律用闸名（冒烟测试／系统测试／单元与集成测试／场景探针／渲染闸等），不裸报编号。 +5. **闸况呈报用闸名**：对话里报验证闸的跑批结果一律用闸名（冒烟测试／系统测试／单元测试／场景探针／渲染闸等），不裸报编号。 ### 简洁细则 diff --git a/design/art/art-assets-checklist.md b/design/art/art-assets-checklist.md index ca3e8b06..b52a60ff 100644 --- a/design/art/art-assets-checklist.md +++ b/design/art/art-assets-checklist.md @@ -27,11 +27,11 @@ |---|---| | 一句话视觉规则 | 明快的地牢，轻快的扫荡，仔细的推理——**明亮像素幻想，全年龄，非暗黑**，角色 2~3 头身 | | 原则一「预告上格」 | 格内绘制优先级 **数字（含色牌）> 小人 > 封印印记 > 变异纹带 > 装饰变体 > 底色**；任何元素禁止遮挡数字字形区；类型微光为底效泛光层，不入遮挡栈 | -| 原则二「明亮为皮，明度分档为骨」 | 暖倾向；数字亮墨直画已开格底（亮墨 L≥0.75 / 已开格底 L 0.08–0.14，art-bible §4.1），对比 ≥4.5:1；色牌 `#F5EAD3` 为复杂格底后备（牌上深墨 L≤0.027）；未开格底 L≥0.30、HSV 饱和 ≤0.55 | +| 原则二「明亮为皮，明度分档为骨」 | 暖倾向；数字亮墨直画已开格底（对比过 WCAG AA，art-bible §4.1）；色牌为复杂格底后备；未开格底亮度地板与饱和上限同 §4.1（门值定值面＝互辨抽测件） | | 原则三「一砖一世界」 | 变体优先换色板不加新资产；危险状态必须**形状+颜色双通道**（色弱灰度可辨） | | 类型预读单通道（§4.6.3） | 未开格 = **类型常显微光**（五组色带 §4.2：芥末黄/黄绿/青/紫罗兰/绯红，色相+明度双码，避 300°–345° 禁入带，样张冻结）；不呈现极性、不泄危险格与安全格（角嵌形状通道已不存在——微光格只留微光） | | 剪影哲学（§5.1） | **所有角色自带轮廓通道：亮色描边+落影底盘**，识别不依赖背景；四类原型见各条目 | -| 语义色规则（§4.2） | 红只说危险（危险红 `#A8321F` 单档）、金只说收益（`#F0A828`）、蓝只说己方（`#2E86DE`）；封印印记现行色 = 封印黑 `#000000`（色史归 art-bible §4.1）；**紫赤 `#8F2F6A` 为 Boss 独占，HSV 色相 300°–345° 全场禁入带**（微光群伤组绯红为类型先验色带域，例外见 §4.2） | +| 语义色规则（§4.2） | 红只说危险、金只说收益、蓝只说己方（各语义色定值面＝ui_kit，art-bible §4.1）；封印印记现行色 = 封印黑（色史归 art-bible §4.1）；**紫赤为 Boss 独占，高饱和紫赤域全场禁入带**（带域定值面＝互辨抽测件；微光群伤组绯红为类型先验色带域，例外见 §4.2） | | UI 形状语法（§7.1，§3.3 存方向指导） | 半拟物：面板=石板圆角矩形（与地砖同圆角率），按钮=可按的砖，仪式确认=圆形蜡封；数据区直角细线无纹理 | **参考图**：`design/art/references/` 三款×2 张（Into the Breach / Moonlighter / Peglin，与圣经点名池一一对应；gungeon 已退场，反面条款见 art-bible §9.2；正面取/弃与反面条款已成文 art-bible §9，反面图证待素材生成后增补）。 @@ -43,7 +43,7 @@ ### 1.1 格子样张（砖面形态定稿闸）⚙ - **要什么**：一张按 art-bible §1.4 参数画成的格子风格试验图。**内容清单与验收四项以 art-bible §1.4 为唯一定义处**（含类型微光呈现组），本条只登记生产视角差异：图类型色板变体组至少两套、样张含至少一处砖缘/岛缘厚度与一格装饰立牌示例（§3.2 呈现基准）。 -- **风格/规格**：色板 token 直接取 §4.1（掩尘 `#C9AF83`、裸土 `#B39A78`、数字墨三档、封印黑、危险红、奖励金、小人蓝、数字色牌）。 +- **风格/规格**：色板 token 直接取 ui_kit 常量组（语义岗清单见 art-bible §4.1：掩尘、裸土、数字墨三档、封印黑、危险红、奖励金、小人蓝、数字色牌）。 - **验收**：art-bible §1.4 四项按序判定（数字可读性 WCAG ≥4.5:1 硬指标 → 格态三形与微光互辨灰度可辨 → 焦点预算 → 图类型换皮抽测）。**通过 = 砖面形态与色板冻结**。 - **来源**：⚙ 脚本管线自产——样张是验收闸本身，必须按圣经参数画，无复用意义。 - **现状**：验收标准已成文，**测试未跑**。 @@ -53,7 +53,7 @@ - **要什么**：按双舞台布局（战斗画面与扫雷图同屏常驻）出的整屏试验图。要锁的四件事：**角色剪影方向 / 动画方案 / 战斗空间 / 敌人层绘制优先级插入位置**；**敌种呈现形态已裁决：全站桩式（主角同站桩、状态小图标挂血条下），卡片式已弃，正式样张按站桩形态单版出样**。 - **风格/规格**：敌人剪影按 art-bible §5.1 四类原型出（见 2.2）；战斗舞台背景=明亮地窟，紫赤仅 Boss；像素尺寸按已定案两档换算（见 §0 通用规格纪律）。 - **验收**：战斗表现「一屏样张的验收标准」（已成文）。 -- **联动**：样张未过，**不启动任何终稿资产与动画设计**（文档明文的排期硬前置）；格边长的计算口径不在本清单——现行唯一出处是 [battle.md](../gdd/ux/battle.md)「棋盘格尺寸公式」，HUD框架只判装板可行性（固定两档分辨率、窗口不可调、格子量增加则格边长相应变小；**档位值已定案 1280×800 + 1920×1080**）。 +- **联动**：样张未过，**不启动任何终稿资产与动画设计**（文档明文的排期硬前置）；格边长的计算口径不在本清单——现行唯一出处是 [battle.md](../ux/battle.md)「棋盘格尺寸公式」，HUD框架只判装板可行性（固定两档分辨率、窗口不可调、格子量增加则格边长相应变小；**档位值已定案 1280×800 + 1920×1080**）。 --- diff --git a/design/art/art-bible.md b/design/art/art-bible.md index 9b30eec6..9fd59877 100644 --- a/design/art/art-bible.md +++ b/design/art/art-bible.md @@ -395,7 +395,7 @@ - **交付形态**：**背景层 1 张（不透明全幅）＋ 围墙层 1 张 ＋ 八个物件层 = 10 张**，其中 9 张透明底、1 张不透明全幅 + 一份坐标表（贴图矩形/命中矩形/z 序）。背景层由**远景片 `bg_far`（2560×734）与地面片 `bg_floor`（2560×866）两片出图、按 y734 拼成一张**——整张一次出图时模型把远山挤到画面下半部，被围墙挡住后完全消失（实测三张里两张山体上缘落在墙顶以下）。接缝整条落在围墙背后，画面无接缝。**篝火例外**：命中矩形只取下半（火堆），上半（火焰）只作特效展示。围墙层落盘按细条裁，不做全幅（全幅约 3.9 MB 显存，细条约 0.35 MB）；**实装落盘矩形 `(0, 203, 1280, 164)`、底锚 y367**（桩身 150px、门柱 164px 终稿锁定值，落带内〔围墙带 (0,203,1280,164)〕）。 - **色彩与氛围依据**：营地的暖由晒白的地面、木色物件与烛光黄承载，安全温馨，与冒险中的地下城形成对比；远景＝正午强日照——天空淡晴蓝（高明度低饱和的清蓝）、远山一整片连续的淡蓝灰山体（禁层叠轮廓带与阴影台阶）、草地与土路晒白，整体淡而退后，近景暖调为主。现行口径 = 本文件 §2.8「全作最暖」（管菜单容器与元进度，不约束背景天空）与本节「情绪与色域」条。本节不复述色值；新增环境色按 §4.1 场景环境子板条款登记（每屏一套、≤32 色、过 §4.2 语义检查与 RGB 三通道差 ≥8/255 两道门）。 - **交互四态（零新素材，全部程序化）**：悬停=**轮廓亮边 + 浮动**（浮动须整像素吸附）；按下=位移 1px；**禁用/未解锁=降明度 + 去饱和**（§2 已缩窄至情绪域，状态表达不受限），**仅锻炉（锻造工坊）与宝箱（秘宝匣）两件会有此态**；已解锁=常态。 -- **钥石余额**：常驻画面顶部的一行小 HUD 栏（高 48px，**浮层覆盖，不挤压画面**）。栏体底=`CAMP_HEADER_BAND` `#6E4526`（§7.2 五 token 对齐表在册色）× 不透明度 0.80；栏内只钥石徽章一件、右位顶格，左位不放件。呈现定值的唯一事实源=[camp](../gdd/ux/camp.md) §顶栏，本节不复述判据。验收：目检〈顶栏成一条可辨窄带，徽章落在带内〉 +- **钥石余额**：常驻画面顶部的一行小 HUD 栏（高 48px，**浮层覆盖，不挤压画面**）。栏体底=`CAMP_HEADER_BAND` `#6E4526`（§7.2 五 token 对齐表在册色）× 不透明度 0.80；栏内只钥石徽章一件、右位顶格，左位不放件。呈现定值的唯一事实源=[camp](../ux/camp.md) §顶栏，本节不复述判据。验收：目检〈顶栏成一条可辨窄带，徽章落在带内〉 - **事实源边界**：解锁条件/价格/存档写入归元进度 GDD 与 `MetaProgression`；素材命名与路径归 `asset-path-map`；清单登记归 `art-assets-checklist` §3.5。 - **已裁（2026-11-01 用户裁）**：① **营地环境子板色值**——不前置拍板：量化场景实际用色后按 §4.1 场景环境子板条款登记（每屏一套、≤32 色、过 §4.2 语义检查与 RGB 三通道差 ≥8/255 两道门）；② **门扇与门洞的高宽比例**——门扇贴图 240×138（锁定 240×147），随门洞 y283–367 压扁重画，坐标按门洞 x520–760 对齐；③ **帐篷的落地尺寸**——251×170 落位 (982, 335)，上端遮住围墙下部。 @@ -508,7 +508,7 @@ ### 8.1 分辨率档位与格边长 - **两档定案**：1280×800（基座）+ 1920×1080，窗口不可调；后续调整走修订。验收：机检〈工程分辨率配置与两档一致〉 -- **格边长取值**：按档位与板形计算——固定档位下格子量增加则格边长相应变小；公式、单位与现行算例的唯一出处 = [battle.md](../gdd/ux/battle.md)「棋盘格尺寸公式」，本节不复述数值。资产侧锁两条比例：**瓦片整格铺满**（32×32 源随格边长缩放，允许非整数倍——瓦片不适用 §8.2 甲类整数倍纪律）、**棋盘小人显示占位 ≤ 0.75× 格边长**。（1920 档已裁决全局等比缩放）验收：机检〈瓦片显示尺寸随格边长、小人占位 ≤0.75×〉 +- **格边长取值**：按档位与板形计算——固定档位下格子量增加则格边长相应变小；公式、单位与现行算例的唯一出处 = [battle.md](../ux/battle.md)「棋盘格尺寸公式」，本节不复述数值。资产侧锁两条比例：**瓦片整格铺满**（32×32 源随格边长缩放，允许非整数倍——瓦片不适用 §8.2 甲类整数倍纪律）、**棋盘小人显示占位 ≤ 0.75× 格边长**。（1920 档已裁决全局等比缩放）验收：机检〈瓦片显示尺寸随格边长、小人占位 ≤0.75×〉 ### 8.2 像素基准与画布 @@ -521,7 +521,7 @@ - **1920×1080 档策略**：全局等比(stretch=canvas_items+aspect **keep**)——16:10 设计在 16:9 窗口=等比 1.35×+左右黑边各 ~96px，构图与 1280×800 基准档完全一致；甲类 1.35 非整数缩放例外注记：轻度宽窄不均系本档位接受代价（像素游戏 shipped 常态），实机目检可感不适→回乙案（1920 独立 2× 基准）重议；乙类同前款。验收：目检〈1920 档构图与 1280 档一致〉 - **画布基准（暂定值）**： - **主角人设原图 = 48×72**（1× 基准，暂定；与站姿降采样可读性验证一致）； - - **棋盘小人 = 32×32 二头身派生版（暂定，允许更小）**——独立资产，自人设定稿压缩派生(character-design §5.4)，不吞数字位、占位 ≤ 0.75× 格边长；板越小占比摩擦越大（13×13 / 14×14 更小，算例见 [battle.md](../gdd/ux/battle.md)「棋盘格尺寸公式」），32px 源档的去留已定终值 = **保留 32×32 源档**（沿「独立小源档」路线；N=12 板下显示占位上限 27px = 0.84 倍，正落本节乙类非整数缩放许可范围，**连豁免都不用再办**），待决标注注销； + - **棋盘小人 = 32×32 二头身派生版（暂定，允许更小）**——独立资产，自人设定稿压缩派生(character-design §5.4)，不吞数字位、占位 ≤ 0.75× 格边长；板越小占比摩擦越大（13×13 / 14×14 更小，算例见 [battle.md](../ux/battle.md)「棋盘格尺寸公式」），32px 源档的去留已定终值 = **保留 32×32 源档**（沿「独立小源档」路线；N=12 板下显示占位上限 27px = 0.84 倍，正落本节乙类非整数缩放许可范围，**连豁免都不用再办**），待决标注注销； - **封印印记参数表（绘制件，非贴图件）**：形与画法见 §3.2。定值——**环外径 = 0.82 × 格边**（26 格 21.3px／46 格 37.7px）；**环壁厚 = 0.11 × 环径**（≈2.3／4.1px）；**十字臂宽 = 0.156 × 环径**（≈3.3／5.9px）；**环外光圈宽 = 0.09 × 格边**（≈2.3／4.1px），向外衰减指数 1.6、峰值 alpha 0.50；圆心 = 格心。色 = 封印黑单色（光圈只改 alpha）。本件随格边连续缩放，**不适用甲类整数倍纪律**（非贴图件，见上条清单）。参数单点 = `ui_kit.gd` 六枚常量 `SEAL_RING_FRAC`／`SEAL_WALL_FRAC`／`SEAL_ARM_FRAC`／`SEAL_HALO_ALPHA`／`SEAL_HALO_GAMMA`／`SEAL_HALO_FRAC`，本节为条款侧对照值。改值须本节与 §3.2 同批修订。验收：机检〈ui_kit 六常量与本表逐值一致〉＋目检〈渲染帧量环径落 82%±1px、光圈不越格边〉 - **站桩立绘显示档 = 三档绝对高**：小型 96 / 中型 144 / 大型 188。逐件归档——小：地精、巨蜘蛛、灰矮人；中：主角、钩爪恐魔、熊地精；大：食人魔酋长、蛛化卓尔、灰矮人石君王。**源 = 原稿像素网格**（八敌 `pixel-1`、主角手修 2× 三态稿），紧裁后原样入包，**禁再降采样**；显示倍率 = 档高 ÷ 源高，NEAREST，宽度随源图比例（高定宽随不变，见上条）。定档依据 = 生物体型（体量=物种体型，非强度线性映射，见 character-design §5.2），**顺序由显示档承载、不由源高承载**。已接受项：中型三件与地精/巨蜘蛛的源高（92/94/123/90/81）低于档高，属放大显示；食人魔酋长显示宽 157 超桩盒 150。验收：机检〈standee_asset_check 逐件显示档高与归档一致、纵横倍率恒等〉＋目检〈同屏体量顺序成立〉 - **站桩立绘排版**：① 区高 B 区 ≈1/3 屏 / C 区 ≈2/3 屏，**扫雷盘原尺寸不缩、格子不变**（区高事实源 = 布局表 `battle_layout.tres`；压缩由 C 区面板空档吸收）；② 站桩内部重排——立绘双脚落石台上缘（弃盒内居中）、**血条+状态/名字行落底排**（立绘→血条→状态 顺序，全场血条对齐一线；血条嵌石板位、台缘线留作地面线、落影保留接地感），状态空时该行退化为名字行；③ 大体档（显示 >150px 级：食人魔酋长/蛛化卓尔/灰矮人石君王）**允许向上溢出盒顶 N px**（N 按实测尺寸算定，**与背景/光柱无关**——现行溢出区恰为临时光柱氛围层〔§6.1 方向稿四柱，x 基准 110/900/1055/1210@1280，`battle_stage_view.gd:47-56`〕，正式舞台背景插画（三关变体）到位后该层直接退役（背景不画光柱），**溢出判定不随之变更**；横向禁止压到顶部中央轮次·阶段指示，溢出上限用真图复算 x 区间定），血条仍落底（落底排的第二个收益=头部探顶不带出血条）；意图徽标悬浮头顶上方（探顶档压胸）；④ 「血条悬浮头顶+立绘盒内居中」排式已弃——盒顶固定 y 与盒内居中在高盒下拉开血条-立绘空洞。验收：目检〈血条一线对齐、大体档溢出不压轮次指示〉 diff --git a/design/art/art-pipeline-tools.md b/design/art/art-pipeline-tools.md index 4e798134..365fa2d6 100644 --- a/design/art/art-pipeline-tools.md +++ b/design/art/art-pipeline-tools.md @@ -1,7 +1,28 @@ # 美术后处理与校验工具清单 -> **性质**：本文件是 `tools/` 下美术资产处理与校验脚本的用法清单。回答三件事：这类资产该跑哪件工具、命令怎么敲、判据与坑在哪。 -> **边界**：只管工具用法，不立美术规格。色值、画布、体量、命名与验收条款归 [art-bible](art-bible.md)（§4.1 主色板、§8 资产与技术规范）和 [art-assets-checklist](art-assets-checklist.md)；命令与源码冲突时以源码现行为准，美术规格冲突时以 art-bible 为准。素材入库与代码接线归 [asset-path-map](asset-path-map.md)，不在本文件。 +> **性质**：本文件是 `tools/` 下美术资产处理与校验脚本的用法清单，兼**执行件门值登记面**——美术数值定值（色值、阈值、档位、帧数、区间）的落点速查索引。回答三件事：这类资产该跑哪件工具、命令怎么敲、判据与坑在哪。 +> **边界**：只管工具用法与定值落点登记，不立美术规格。概念、规则与方向归 [art-bible](art-bible.md)；命令与源码冲突时以源码现行为准，美术规格冲突时以 art-bible 为准。素材入库与代码接线归 [asset-path-map](asset-path-map.md)，不在本文件。 + +## 执行件门值登记（定值落点速查索引，2026-11-07 立） + +美术数值定值的落点速查——每行＝一个定值面与其承载件；改值＝改对应执行件并跑其守门断言，文档侧对照值同批核对： + +| 定值面 | 承载件 | +|---|---| +| 色值 token 全板（语义色/墨族/材质色/呈现态） | `game/presentation/views/ui_kit.gd` 常量组（色板唯一来源）＋ theme README 溯源表 | +| token 存量近色互查与新增色第二道门 | `tools/palette_check.py`（素材侧）＋ `palette_token_pairwise_test.gd`（常量面守门，含在册豁免账） | +| 微光五组色值与呈现参数 | `ui_kit.gd` 微光常量组＋`type_glow_test.gd` 守门断言 | +| 未开格底/图类型色板准入门（亮度地板/饱和上限/禁入带/近色容差）与**世界底层两子带** | `tools/glow_discrimination_sheet.py` 门值常量（本件「判据或口径」节） | +| 已开格底渲染面亮度 | `game/presentation/views/tile_palette.gd` 归一化目标常量；对比判据＝`game/probe/ui_contrast_probe.gd` | +| 文字对比门槛（WCAG AA）与整屏有效色数上限 | `tools/shot_checker.py` 常量（`ui_contrast_probe` 同源） | +| 封印印记六参数 | `ui_kit.gd` `SEAL_*` 六常量＋`seal_mark_params_test.gd` | +| 站桩显示档三档与源档逐件 | `standee_present_values_test.gd` 钉值＋`tools/standee_asset_check.py` | +| 动画帧数档（待机/攻击/受击） | `animation_frame_spec_test.gd` 规格表（序列帧资产入包后逐件判） | +| 字号六档与下限 | `ui_kit.gd` `FS_*` 常量组 | +| 屏级分区几何/带高 | `game/data/tables/battle_layout.tres`（数据索引，art-bible 直指） | +| 营地场景坐标群（落盘矩形/命中矩形/z 序/桩柱高） | `camp-scene-prompts.md` 坐标表＋落盘件 | +| 棋盘结构件 px（墨线/暗带/投影/悬崖） | `board_world.gd`/`board_view.gd` 常量＋渲染闸 golden 基线 | +| 视野迷雾半径/提灯加成/记忆态常量 | `board_view.gd` `FOG_*` 常量＋`ui_kit.gd` 迷雾常量组 | > **分工**：[art-prompts](art-prompts.md) 管角色级提示词与五步出图流程，[camp-scene-prompts](camp-scene-prompts.md) 管营地场景分层提示词与四步流程；两卡只把「后处理」一步指到本文件。提示词怎么写出图、出完图怎么处理，是两件事。 > **命令前提**：以下命令均在仓库根执行。素材不入 git，worktree 缺件时部分脚本回退主检出 `D:/code/g-plan2`，部分直接返回错误，见各节「已知坑与适用边界」。 diff --git a/design/art/art-status-checklist.md b/design/art/art-status-checklist.md index b7b8640c..5b447569 100644 --- a/design/art/art-status-checklist.md +++ b/design/art/art-status-checklist.md @@ -17,8 +17,8 @@ | 素材 | 状态 | 需求文档 | |---|---|---| -| 主角战斗小人（待机/攻击/受击三态） | ✅ 已交付：B 区站桩三态按原稿分辨率入包、显示按档缩放落位（显示档=中档 144，源=手修 2× 三态稿，art-bible §8.2），机检全绿；挂事件切换、结算回 idle 短驻自回；棋盘 1.5×/脚锚25%/椭圆影在役 | [character-design](character-design.md) + [art-prompts](art-prompts.md) §2 | -| 八敌种形象（L2 熊地精=bugbear 复用，不单列） | ✅ 已交付：B 区站桩八敌真图服役——八件源=原稿不降采样入包、显示按档缩放落位（三档绝对高 96/144/188，art-bible §8.2），闸件全绿；character_enemy_<键>.png 按常量入位，字形回退退役为缺位兜底；素材不入 git 本地在盘 | [art-bible](art-bible.md) §5 + [art-prompts](art-prompts.md) §3 | +| 主角战斗小人（待机/攻击/受击三态） | ✅ 已交付：B 区站桩三态按原稿分辨率入包、显示按档缩放落位（显示档=中档，源=手修 2× 三态稿，art-bible §8.2），机检全绿；挂事件切换、结算回 idle 短驻自回；棋盘 1.5×/脚锚25%/椭圆影在役 | [character-design](character-design.md) + [art-prompts](art-prompts.md) §2 | +| 八敌种形象（L2 熊地精=bugbear 复用，不单列） | ✅ 已交付：B 区站桩八敌真图服役——八件源=原稿不降采样入包、显示按档缩放落位（三档绝对高，art-bible §8.2），闸件全绿；character_enemy_<键>.png 按常量入位，字形回退退役为缺位兜底；素材不入 git 本地在盘 | [art-bible](art-bible.md) §5 + [art-prompts](art-prompts.md) §3 | | 意图准备动画三档 | ◐ | [art-bible](art-bible.md) §4.6.4 | ## P2 图标与格面（可与样张并行） diff --git a/design/art/character-design.md b/design/art/character-design.md index 0bb507fe..dcae2584 100644 --- a/design/art/character-design.md +++ b/design/art/character-design.md @@ -67,7 +67,7 @@ - **主色域 = 物种本色**，不受圣经 §4.2 语义色禁则约束（该禁则管格面与 UI 的逻辑色，角色身体主色豁免）；**两例外**：禁入带 300°–345° 全角色禁入（仅 drider/duergar_king 两 Boss 独占）、蓝族禁入敌方主色（§5.4 同款）。 - **L2 熊地精 = bugbear 复用**（第二关三行，显示名熊地精系，非独立键）：同剪影**换色板不换形**（色板替换走脚本管线——原则三"先换色板"的角色侧应用）；变体主色避小人蓝族与禁入带。 - 每敌种出 2–3 版候选（清单 §2.2）；受击反馈/死亡表现/顺位标记三类呈现下限见圣经 §4.6.4 资产需求行。 -- **立绘显示档（定值单点 = 圣经 §8.2 站桩立绘显示档条，本档指路不复述）**：三档绝对高 96/144/188，逐件归档、源档与缩放规则一律见圣经 §8.2——**数值权威 = 圣经 §8.2**（定值单点纪律，圣经 §8 头注）；归档经三体型约束校验（§5.2）确认；派生管线与排版规范同归圣经 §8.2。 +- **立绘显示档（定值单点 = 圣经 §8.2 站桩立绘显示档条，本档指路不复述）**：三档绝对高，逐件归档、源档与缩放规则一律见圣经 §8.2——**数值权威 = 圣经 §8.2 指向的执行件**（定值单点纪律，圣经头注）；归档经三体型约束校验（§5.2）确认；派生管线与排版规范同归圣经 §8.2。 - **钩爪恐魔「宽≥高」豁免登记（待样张终审）**：定档源 58 高窄条束状剪影（长臂圆钩），宽高比 <1，与 §5.1 普通怪「近圆墩形宽≥高」冲突——按体量=生物天性（§5.2）登记豁免：以长臂束状轮廓为识别锚，不强行压成墩形；样张（圣经 §1.4）终审复验灰度剪影可辨性。 ## 5.6 意图准备动画三档（规格承载节） diff --git a/design/engineering/architecture/architecture.md b/design/engineering/architecture/architecture.md index 1a59f1ef..f486a7ce 100644 --- a/design/engineering/architecture/architecture.md +++ b/design/engineering/architecture/architecture.md @@ -2,12 +2,12 @@ ## 文档状态 -- 版本：1.36 +- 版本：1.37 - 引擎：Godot 4.7.2-stable（GDScript 单语言；2026-09-07 锁定） - 评审模式：solo（`review-mode.txt`，2026-09-12 用户拍板——TD/LP 门禁按 solo 跳过，用户授权架构产出自主推进、迭代期回调） - 覆盖 GDD：现行全集（根索引＝`design/gdd/02-系统清单.md`，文档树构成以根索引为准） - 事实源地位：本文是架构事实的唯一来源——分层/所有权/数据流/API 边界/测试与质量域均以本文为准；历史决策沿革查 git commit log，不另设决策文档体系 -- 实现实证：`game/`（2026-09-10 起开发，**现为完整游戏开发版本，已非垂直切片**；测试层级＝冒烟/单元/集成/系统四级＋UI 探针与渲染 golden（2026-10-22 用户裁），闸机按改动域分跑在役）——本文档的分层/所有权/数据流均经实现验证，非纯纸面设计 +- 实现实证：`game/`（2026-09-10 起开发，**现为完整游戏开发版本，已非垂直切片**；测试层级＝冒烟/单元/系统三级＋UI 探针与渲染 golden（2026-10-22 用户裁立；2026-11-07 用户裁层级合并，跨系统闭环套件归单元层），闸机按改动域分跑在役）——本文档的分层/所有权/数据流均经实现验证，非纯纸面设计 - 主程序可行性：跳过 — solo 模式 --- @@ -172,7 +172,7 @@ | **CampSceneView**（`views/camp_scene_view.gd`，营地场景根视图，已建件） | 营地场景图唯一呈现件：十层贴图铺底（层序按 layout 表 z 序；`camp_scene_layout.tres` fail-fast 校验＋七命中区几何红线——camp_scene_layout_test 承载）、七物件命中区命中即发 object_pressed（组合根路由大门/篝火/笔记本/四界面）、反参照纪律（场景根零文字按钮）、登记模态初始隐（boot 态不盖菜单） | 构造注入（贴图经 `UiKit.TEX_CAMP_*`、layout 表经 ConfigDB 表现域容器）；object_pressed 信号外发；open/close 经营地域子容器寻址 | camp_screen（宿主挂载）；ConfigDB；组合根（路由消费） | Control＋TextureRect 树 | | **营地四子界面视图**（`views/camp_sub_view_base.gd`＋forge_view/tree_view/treasure_view/codex_view，功能窗口公共壳＋四件，已建件） | 营地五功能窗口的四个承载视图（锻造工坊/天赋树/秘宝匣/图鉴）＋公共壳（窗口壳/行板/关闭钮；生涯页挂笔记本路由不经此族）；模态栈单口 open/close、五窗互斥单开；presenter 承接面零回表（树购买/锻造三意图经既有写口族） | 各 view open/close＋意图信号外发；关闭钮 pressed | camp_shop_presenter／MetaProgression 写口（经组合根）；CampRefreshBus（刷新广播消费） | Control | | **camp_esc_overlay＋MainEscFlow**（`views/camp_esc_overlay.gd`＋`presentation/main_esc_flow.gd`，Esc 浮窗视图＋四态路由件，已建件） | Esc 浮窗三钮视图（返回主菜单/设置/退出）＋Esc 四态路由静态件（根态唤起/再按关窗/功能窗开着先关最上层窗〔camp.md v2.3 定稿〕/设置开态不误关；菜单语境不唤起）；**main._unhandled_input＝产品码首个键盘输入入口**（契约 9——事件驱动、禁 Input 轮询、不挂 ui_cancel、pressed 非 echo） | flow.open/close 路由口；三钮 pressed 意图信号（经组合根接线）；入口方法公开化（main 转发调用的入口去下划线——on_esc_input/is_camp_context 先前已公开） | 组合根（_unhandled_input 前置与意图消费）；模态栈（关窗单口）；screen_flow（设置/返回动线） | Control＋静态件 | -| **CampHudBand**（`views/camp_hud_band.gd`，营地顶栏 HUD 件，已建件） | 顶栏 48px 全宽窄条：钥石余额 badge 唯一呈现（单口取现值、显式刷新才变）；set_hud_band 预留位落座 | badge 文本投影；refresh 时取现值 | CampRefreshBus（挂册广播）；MetaProgression 钥石读 | Control | +| **CampHudBand**（`views/camp_hud_band.gd`，营地顶栏 HUD 件，已建件） | 顶栏 48px 全宽窄条两呈现物：栏体色面（UiKit 出口 camp_hud_band_surface 落装——CAMP_HUD_BAND×α0.80 全宽铺满、不吃点击）＋钥石徽章（右位顶格：徽章右缘＝栏右缘−12）；badge 文本单口取现值、显式刷新才变；set_hud_band 预留位落座 | badge 文本投影；refresh 时取现值 | CampRefreshBus（挂册广播）；MetaProgression 钥石读；UiKit（栏体色面出口 camp_hud_band_surface） | Control | | **CampRefreshBus**（`views/camp_refresh_bus.gd`，营地刷新单口件，已建件） | 营地刷新单口唯一承载：进档尾与营地写口尾触发 refresh 广播（八写口尾改路由），现开界面与 HUD 同步取现值 | 挂册/refresh 广播 | 组合根（触发点接线）；四子界面与 CampHudBand（消费） | 无（RefCounted 信号件） | | **board_hover**（`views/board_hover.gd`，悬停预承诺呈现域件，已建件） | 悬停反馈域唯一承载：三语义光标、目标格边框、BFS 路径预览、chord 双击首遇锚；_r0 出生展开区成员留宿主 | 构造＝引用束注入 7 项（cells/minesweeper/diggable 引用＋格命中换算/光标写入/hover_forbidden/chord_attempted 四 Callable）；三入站口留宿主委托；hover_probe 读面留宿主；公开方法面 7（七口公开化——rebind/reset/refresh_after_paint/hover_at/detect_chord/on_shell_mouse_exited/hover_pos） | board_view（宿主）；输入事件经宿主入站口 | 无（RefCounted） | | **cell_base_layer／cell_mark_overlay**（`views/`，单格两绘制域件，已建件） | 单格绘制域拆分（入参与该层绘制命令同件）：基座层（底面/描边/立面/投影/接触带/倒角，12 成员）与标识叠加层（标记/字形/徽章/点迹/高亮/退色，14 成员）；徽章遮罩走构造交付 Callable（`_mask_set`）；宿主 _draw 退为六步时序器，宿主实测类变量 10 | 构造注入；绘制命令由宿主 _draw 按层序调用 | board_cell_unit（宿主）；gdstyle 键各文件独立计数（12/13 均 ≤15） | 无（RefCounted） | @@ -245,7 +245,7 @@ |---|---|---|---|---| | **run_smoke**（冒烟测试运行器） | `tools/run_smoke.py` | 冒烟测试总入口与判定权：headless 以项目运行目标拉起 `res://tests/smoke_boot.tscn`（极小启动场景——autoload 在位、配置表全载、主屏实例化，零逻辑判定）+ 三闸判定 | 进程退出码（0=PASS / 1=FAIL） | 三闸齐备、判定无洞：①退出码 = 0；②摘要行「[smoke] 摘要：N 项检查，0 项失败」在案且失败数为 0；③输出扫 `SCRIPT ERROR` / `Parse Error` 标记行。外部 wall-clock 超时在位（超时 = FAIL） | | **run_system_test**（系统测试运行器） | `tools/run_system_test.py` | 系统测试总入口：headless 跑真实玩法路径断言面（宿主=`res://tests/system_test.gd`）+ 三闸判定（口径同 run_smoke，摘要行兼容两种宿主格式） | 进程退出码（0=PASS / 1=FAIL） | 三闸齐备（同 run_smoke：退出码／摘要失败数／脚本错误扫描；wall-clock 超时在位） | -| **run_all**（单元与集成测试） | `game/tests/run_all.gd` | 64 套统一入口（61 单元＋3 集成，2026-10-28 实数）：套件 manifest 逐条「套件 → 期望退出码」，致命类 expect=1 独立子进程实跑；`negative` 字段标负面套件（仅豁免错误扫描一闸）；选跑态 `--only=<词[,词…]>`（直跑形态对套件路径子串匹配只跑命中套件，零命中＝用法错 quit(2)，仅供开发期最窄确认——不产闸回执、不作验收凭据，批末全量闸不经选跑分支） | 逐套件结果 + 汇总退出码（任一套件失败 quit(1)） | 套件级退出码协议在位；三硬闸齐备（入口内扫子套件输出 + 编排层扫 `unit.log`；`Kit.finish` 零断言返回专用码 2）。子进程输出须经系统命令解释器重定向落盘再读——`OS.execute` 的输出管道在本机恒空 | +| **run_all**（单元测试） | `game/tests/run_all.gd` | 65 套统一入口（65 单元，2026-11-07 实数——跨系统真实路径闭环 3 套件归并单元层）：套件 manifest 逐条「套件 → 期望退出码」，致命类 expect=1 独立子进程实跑；`negative` 字段标负面套件（仅豁免错误扫描一闸）；选跑态 `--only=<词[,词…]>`（直跑形态对套件路径子串匹配只跑命中套件，零命中＝用法错 quit(2)，仅供开发期最窄确认——不产闸回执、不作验收凭据，批末全量闸不经选跑分支） | 逐套件结果 + 汇总退出码（任一套件失败 quit(1)） | 套件级退出码协议在位；三硬闸齐备（入口内扫子套件输出 + 编排层扫 `unit.log`；`Kit.finish` 零断言返回专用码 2）。子进程输出须经系统命令解释器重定向落盘再读——`OS.execute` 的输出管道在本机恒空 | | **probe_gate**（场景探针） | `tools/probe_gate.sh` | headless 场景探针段编排（单一形态十件恒跑）：ui_input_probe / ui_struct_probe / layout_probe / ui_contrast_probe / **screen_flow_probe**（屏壳切换）/ ui_click_probe（行为走查）/ ui_probe / ui_tune_probe / t17_defer_probe / fx_probe；孤儿 Godot 预清 + 批末残留清点（必须 0） | 段级 FAIL 输出 + 汇总退出码 | 每段 timeout 守卫在位（挂死 124/137 = FAIL，不静默）；判定统一走 `verdict` 函数——退出码为唯一权威判据，PASS 串降级为附加判据，逐段跑 `tools/error_scan.py` | | **render_gate**（视觉 golden） | `tools/render_gate.sh` | 窗口化渲染闸：①shot_probe 七屏截图 → shot_checker A-D 语义断言；②fx_shot_probe / board_shot_probe 取证（超时/零字节/文件缺失任一 = FAIL）；③棋盘 golden 逐像素容差比对（差 ≤16 / changed ≤2%，provisional）+ 菜单 golden；④批末孤儿残留清零；⑤三段探针日志逐段脚本错误扫描 | 段级 FAIL 输出 + 汇总退出码 | 查退出码在位（每段 timeout 守卫 + 退出码/取证文件双检）；SCRIPT ERROR 扫描在位（逐段 `tools/error_scan.py`，标记与 run_smoke 同源）；断言数下限不适用（判定主体 = golden 容差与取证文件存在性，非断言计数） | | **static_scan**（静态扫描域） | `game/tests/static_scan.sh` | 静态扫描域 S1–S10 可执行载体（grep 规则 + `tools/audit_type_hints.py`〔S9〕+ `tools/audit_file_headers.py`〔S10〕） | fail 聚合退出码（任一硬失败规则命中即 exit 1） | 查退出码在位；SCRIPT ERROR 扫描与断言数下限不适用（逐规则命中即红，无运行时错误面与断言计数）；S3 现为 warning 级、不参与 fail 判定（见下表） | @@ -301,13 +301,12 @@ S11/S12 扫描面覆盖全域，故 sim/probe/tests 的术语与旧件面**在 ### 三层承载与判定原则 -测试分标准四级＋UI 探针（2026-10-22 用户裁），各有在册承载与入闸方式（细目见 `game/tests/README.md`）： +测试分标准三级＋UI 探针（2026-10-22 用户裁立；2026-11-07 用户裁层级合并——跨系统真实路径闭环套件归单元层；识别三元组归 test-conventions §1.1），各有在册承载与入闸方式（细目见 `game/tests/README.md`）： | 层 | 判什么 | 承载 | 入闸 | |---|---|---|---| | 冒烟测试 | 这版活着吗（零逻辑判定） | `game/tests/smoke_boot.tscn/.gd` | `run_smoke.py`（冒烟测试闸） | -| 单元测试 | 领域类的原子行为对不对（从对外方法进、钉对外可观测面——写法判据归 test-conventions §8.2） | `game/tests/unit/` | `run_all.gd`（单元与集成测试闸） | -| 集成测试 | 跨系统闭环对不对 | `game/tests/integration/` | 同上（同一入口同一协议） | +| 单元测试 | 受控裸环境断言面：领域类原子行为＋跨系统真实路径闭环（从对外方法进、钉对外可观测面——写法判据归 test-conventions §8.2） | `game/tests/unit/` | `run_all.gd`（单元测试闸） | | 系统测试 | 真实玩法路径断言面 | `game/tests/system_test.gd` | `run_system_test.py`（系统测试闸） | | UI 探针＋渲染 golden | 场景切换与观感 | `game/probe/*.tscn` 探针 | `probe_gate.sh`（场景探针闸）、`render_gate.sh`（渲染闸） | diff --git a/design/engineering/code-conventions.md b/design/engineering/code-conventions.md index 2efb9934..2bfbb738 100644 --- a/design/engineering/code-conventions.md +++ b/design/engineering/code-conventions.md @@ -78,7 +78,7 @@ 10. **`# rng-seed-exempt` 标记豁免通道**——S1/S2 随机函数扫描对该行豁免；限定用途=非玩法 RNG 消费面的引擎熵（现行例：组合根种子编辑框空态取 `randi()`——建种子不进玩法封闭流）；非产品码三目录自建随机源的定种要求见第 13 条。 11. **`--script` 模式禁裸 autoload 标识符**——`ConfigDB`/`RngService` 等 autoload 名在 `--headless --script` 模式编译器不解析（parse error）；产品码与测试夹具一律经节点路径取用（`get_node("/root/…")`／`AUTOLOAD_PATH_*` 常量）；静态扫描域 S5 硬失败承载在位。 12. **Variant 参数化现行口径**——账本类字典/数组标注 `Dictionary[Variant, Variant]`/`Array[Variant]` 即合格（满足 R1）；元素类型精化列后续事项、不入硬纪律，口径变更须用户裁决后续批次另行写入。 -13. **静态扫描适用域按来源分档（2026-11-03 架构审查 P1 余项裁）**——S 系静态扫描（S1–S13）的扫描面一律止于产品码三目录，`game/tests`／`game/probe`／`game/sim` 不进任何 S 系扫描面；这三目录的可靠性由运行期通道承接，各通道是：`game/tests`＝冒烟·单元与集成·系统测试三闸、`game/probe`＝场景探针与渲染 golden 两闸（同目录内 `type_glow_shot_probe` 是人工取证件、`probe_ui_util` 是探针共用面，两者不入闸）、`game/sim`＝不入 CI，属用户手动发起的调参与数值测量批量。三目录**允许**自建 `RandomNumberGenerator`，条件＝**必须显式定种**（改前改后读数要用同种子对拍，这是全项目测量口径）；三目录真正禁止的形态是不定种随机——`randomize()` 与全局 `randi()`／`randf()`／`randf_range()`，一旦命中那次运行结果不可复现，读数与取证一并失效。这条对三目录的部分目前**无机器闸**（S1/S2 扫描面不含它们）：扩面需给每处合法定种挂 `rng-seed-exempt` 注记、只拦得住新增，2026-11-03 用户裁不扩，改由本条文字＋批末独立验收审计的人工评审承载。术语口径：`tools/run_all_gates.sh` 里的「测量面」指 `game/tests`＋`game/sim`（影响面选闸用语，`game/probe` 不在其中——改探针必须跑场景探针与渲染闸），与本条分档无关；本文不再用「测量面」统称这三个目录。 +13. **静态扫描适用域按来源分档（2026-11-03 架构审查 P1 余项裁）**——S 系静态扫描（S1–S13）的扫描面一律止于产品码三目录，`game/tests`／`game/probe`／`game/sim` 不进任何 S 系扫描面；这三目录的可靠性由运行期通道承接，各通道是：`game/tests`＝冒烟·单元·系统测试三闸、`game/probe`＝场景探针与渲染 golden 两闸（同目录内 `type_glow_shot_probe` 是人工取证件、`probe_ui_util` 是探针共用面，两者不入闸）、`game/sim`＝不入 CI，属用户手动发起的调参与数值测量批量。三目录**允许**自建 `RandomNumberGenerator`，条件＝**必须显式定种**（改前改后读数要用同种子对拍，这是全项目测量口径）；三目录真正禁止的形态是不定种随机——`randomize()` 与全局 `randi()`／`randf()`／`randf_range()`，一旦命中那次运行结果不可复现，读数与取证一并失效。这条对三目录的部分目前**无机器闸**（S1/S2 扫描面不含它们）：扩面需给每处合法定种挂 `rng-seed-exempt` 注记、只拦得住新增，2026-11-03 用户裁不扩，改由本条文字＋批末独立验收审计的人工评审承载。术语口径：`tools/run_all_gates.sh` 里的「测量面」指 `game/tests`＋`game/sim`（影响面选闸用语，`game/probe` 不在其中——改探针必须跑场景探针与渲染闸），与本条分档无关；本文不再用「测量面」统称这三个目录。 --- diff --git a/design/engineering/doc-conventions.md b/design/engineering/doc-conventions.md index 1659f09b..1d66a3ba 100644 --- a/design/engineering/doc-conventions.md +++ b/design/engineering/doc-conventions.md @@ -68,12 +68,12 @@ | 一系统一文档 | 不建 analysis 推演件；两三句能说清的"为什么"直接写进设计目的或规则正文 | | 正文只写现行规则 | 禁删除线、"（作废）"、"（日期+拍板）"式注记；审计信息入对应文档附录 | | 禁实现内容 | 系统文档与概念文档全文禁写实现细节——代码路径（`.gd`／`.py`／`.sh` 与运行时文件路径）、测试文件名、断言名、类名／方法名／信号名／常量名／调试与遥测入口名、提交号一律不出现；唯一例外＝数据索引（`game/data/tables/*.tres` 与 `game/data/schemas/` 的表路径与表名、表字段名与表内枚值、存档键、封闭词表标签）。实现事实归 `architecture.md`；验收标准只写玩家或系统可观测面。本行由文档域闸的能力审计机检两个可判死的面（带后缀路径、反引号调用形态），其余靠写卡段人工核对；闸件清单与域划分的唯一出处＝`tools/run_all_gates.sh` 头部 | -| 正文单点维护 | 一条规则句只写在定义它的那份文档（owner 文档）；其他文档要引用时写指针或语义概括，禁复制色值、尺寸、路径等可核对的具体值——上一句管不住数值之外的双写，本句补上。豁免面 = 执行侧文件必须带字面值才能工作时（生图提示词里的十六进制色、脚本参数），转写不算双写，但该文件头部必须写明"冲突时以 owner 文档为准" | +| 正文单点维护 | 一条规则句只写在定义它的那份文档（owner 文档）——此前半句全域适用；后半句（其他文档要引用时写指针或语义概括，禁复制色值、尺寸、路径等可核对的具体值）适用域＝`design/gdd/**`（GDD 设计文档；2026-11-07 用户裁收窄——美术圣经与 UX 呈现规格层为可带值参考层，不在后半句约束内）。豁免面 = 执行侧文件必须带字面值才能工作时（生图提示词里的十六进制色、脚本参数），转写不算双写，但该文件头部必须写明"冲突时以 owner 文档为准" | | 禁写变更记录 | 文档与代码文件内一律禁设「版本历史／修订记录／变更记录／修改记录／更新记录／更新日志」节或表格，禁逐版本叙述「改了哪些条款」；沿革与改动明细只进 git commit log。版本号可作为文档现行身份标记出现在文首状态行与正文引用中，但不得再挂变更表 | | 后置 ≠ 删除 | P1/P2 后置内容逐条列出；复活后置项 = 修订文档，禁静默加回 | | 活体清单不冻结计数 | 对会生长的清单（文档树构成、UI 层项、RNG 流词表等）不写死计数与枚举——写指针到 owner（根索引/常量表/实现文件），现状值由 owner 承载；历史计数只进 git 提交信息 | -**数值纪律（概念/实现分界，2026-11-05 用户立）**：GDD 概念文档只定概念、机制与规则——是什么、有什么、为什么；数量面（多大、多少、多大概率）与呈现实现细节不进概念文档正文。分工三处：取值域与字段契约归 `game/data/schemas/*.gd`（表结构定义＋域校验执法，provisional 随值标注）；现行值归 `game/data/tables/*.tres`；呈现实现规格（冻结公式、像素值、动效参数）居 `design/gdd/ux/`＝呈现实现设计规格层，豁免概念纯度约束。存量系统文档的旧调参表节由独立清扫批消化，消化期不作机检对象（现行闸无此项判据）。 +**数值纪律（概念/实现分界，2026-11-05 用户立）**：GDD 概念文档只定概念、机制与规则——是什么、有什么、为什么；数量面（多大、多少、多大概率）与呈现实现细节不进概念文档正文。分工三处：取值域与字段契约归 `game/data/schemas/*.gd`（表结构定义＋域校验执法，provisional 随值标注）；现行值归 `game/data/tables/*.tres`；呈现实现规格（冻结公式、像素值、动效参数）居 `design/ux/`＝呈现实现设计规格层，豁免概念纯度约束。存量系统文档的旧调参表节由独立清扫批消化，消化期不作机检对象（现行闸无此项判据）。 **登记处唯一性**：`design/registry/`（`entities.yaml`／`architecture.yaml`）已注销删除，禁再建第二处事实登记——术语进 术语表、数值进 `.tres`、架构进 架构文档、影响面靠全仓搜索概念规范名得出。强制收口条款： @@ -181,7 +181,7 @@ 设计线段与下游段同条并存是合法形态：状态行里出现过的**每条设计线各自留最新一段**，跨线依赖不阻塞本条推进（文档线闭合后写卡、美术线仍未出图，就把 `文档设计已闭合` 与 `待美术设计` 并写）。「写卡前本条要落的那条设计线必须已闭合」是实现侧的执行义务，由编排段查卡片凭据核对，不靠标题声明——闸只查同线并现多段。 -状态行只写状态词：去掉特批标记与「（备选）」后缀后，残留任何括号即违规。闭合类状态词（文档设计已闭合／美术设计已闭合／已写卡／已写入）的证据——设计定稿路径+版本、art-bible 条款版本、需求卡片路径、复核报告路径（「已写卡」段另须报这一项，2026-11-05 用户立规；对文件名日期 ≥2026-11-06 的卡生效，旧卡不回头改，核对由 `tools/pipeline_gate.py` 的卡片复核判据到卡正文做）、落点文档+版本——一律写在实况的关联文档清单里，由流水线闸到正文核对；已编迭代 N 段的交叉核依据＝实况清单里的需求卡片路径。 +状态行只写状态词：去掉特批标记与「（备选）」后缀后，残留任何括号即违规。闭合类状态词（文档设计已闭合／美术设计已闭合／已写卡／已写入）的证据——设计定稿路径+版本、art-bible 条款版本、需求卡片路径（「已写卡」段的复核凭据＝卡内「复核记录」节，2026-11-06 用户裁：不另设复核报告文件；对文件名日期 ≥2026-11-06 的卡生效，旧卡不回头改，核对由 `tools/pipeline_gate.py` 的卡片复核判据到卡正文做）、落点文档+版本——一律写在实况的关联文档清单里，由流水线闸到正文核对；已编迭代 N 段的交叉核依据＝实况清单里的需求卡片路径。 三种条目形态与一种后缀： diff --git a/design/engineering/process-conventions.md b/design/engineering/process-conventions.md index 4a9764ae..63e07139 100644 --- a/design/engineering/process-conventions.md +++ b/design/engineering/process-conventions.md @@ -10,9 +10,9 @@ 主工作区（master 检出）只作合并落点，一切开发/设计改动禁止直接发生在主工作区（2026-10-31 用户裁恢复；验证模型＝批内按 §4 改完即测、合回后远端 CI 是唯一强制全量验证点，细则见本节第 3 条）： 1. **worktree 车道（一切面）**：每回合先建独立 worktree（建区粒度＝回合，会话单区细则见第 5 条）：`git worktree add ../g-plan2-<任务名> -b <任务分支>`；建区后立刻跑 `tools/setup_worktree_userdir.sh`——给该区独立 Godot user 目录（测试夹具、试玩日志、截图产物不与其他区共用；主区不生成，真实档保持原位）。所有改动与提交都在 worktree 内自由进行——commit 点零钩子检查（`tools/hooks/pre-commit` 已删除）。豁免面仅 `.zcode/`（钩子与配置）与 `.qoder/`（本机 harness 配置）允许主工作区直改——两份实测均不入 git（走 worktree 反而带不进去，改动只对本机生效） -2. **收口顺序（固定）**：**冻结 → 件核 → 并 master → 重塑 → 主区合回 → 删区**——代码与断言改完即冻结，全仓件核 grep 查残留；master 已被别的批次推进时先在 worktree 内 `git merge master` 解冲突（必须在合回之前，合回后才并＝CI 验的是中间态）；**重塑**＝迭代分支（iter 形）合回前执行 `python tools/reshape_cards.py`，把分支线性史按卡末态快照压成一卡一笔（可选追加一笔纯文档收尾），master 台账由此每卡一行——工具自带「重塑前后树逐字节一致」断言与 backup 分支，不改任何文件内容；非迭代批免重塑；然后主工作区 `git merge --no-ff <任务分支>`（pre-merge-commit 钩子先跑前置检查——冒烟＋单元与集成全套件约 2 分钟，红则停合并提交，细则见第 4 条 ③）——这是主区唯一合法写动作（合回守卫对迭代分支数卡校验，未归卡提交拦下）。**合回落地即 `git worktree remove`＋删分支（合回即删，2026-09-19 原裁）；post-merge 钩子已在合回落地时自动触发 CI，红态不回滚合并——新开修复 worktree（`fix-<任务名>` 分支，非 iter 形免重塑免数卡）修复提交再合，落地复验追绿后删修复区**。批内的验证义务按 §4 改完即测铁规履行——改完即测自己改过的那部分，不请示、不等点名；收口顺序本身不设跑批关口。**卡片复核前置判据（2026-11-05 用户裁）**：需求卡片的 grilling 复核先于卡片提交、卡片提交先于合回——复核未跑完、缺陷清单未裁完，禁把卡片落 commit（落了也不算成立），`master` 永不落未成立卡；本条与 §2 段三出口铁律、doc-conventions §12.1「已写卡」凭据同判。 +2. **收口顺序（固定）**：**冻结 → 件核 → 并 master → 重塑 → 主区合回 → 删区**——代码与断言改完即冻结，全仓件核 grep 查残留；master 已被别的批次推进时先在 worktree 内 `git merge master` 解冲突（必须在合回之前，合回后才并＝CI 验的是中间态）；**重塑**＝迭代分支（iter 形）合回前执行 `python tools/reshape_cards.py`，把分支线性史按卡末态快照压成一卡一笔（可选追加一笔纯文档收尾），master 台账由此每卡一行——工具自带「重塑前后树逐字节一致」断言与 backup 分支，不改任何文件内容；非迭代批免重塑；然后主工作区 `git merge --no-ff <任务分支>`（pre-merge-commit 钩子先跑前置检查——冒烟＋单元全套件约 2 分钟，红则停合并提交，细则见第 4 条 ③）——这是主区唯一合法写动作（合回守卫对迭代分支数卡校验，未归卡提交拦下）。**合回落地即 `git worktree remove`＋删分支（合回即删，2026-09-19 原裁）；post-merge 钩子已在合回落地时自动触发 CI，红态不回滚合并——新开修复 worktree（`fix-<任务名>` 分支，非 iter 形免重塑免数卡）修复提交再合，落地复验追绿后删修复区**。批内的验证义务按 §4 改完即测铁规履行——改完即测自己改过的那部分，不请示、不等点名；收口顺序本身不设跑批关口。**卡片复核前置判据（2026-11-05 用户裁）**：需求卡片的 grilling 复核先于卡片提交、卡片提交先于合回——复核未跑完、缺陷清单未裁完，禁把卡片落 commit（落了也不算成立），`master` 永不落未成立卡；本条与 §2 段三出口铁律、doc-conventions §12.1「已写卡」凭据同判。 3. **合回后验证（远端 CI，2026-11-03 用户裁）**：git merge 合回 master 落地后 post-merge 钩子（`tools/hooks/post-merge`）自动 `git push origin master` 触发远端 CI（Gitea Actions，runner＝Mac 本机 host 模式），工作流按改动域分流（分流算法单点＝`tools/ci/domain_route.sh`：游戏码批＝两域全量含渲染闸，文档批＝文档域秒级闸，纯闸件/管线批＝零触发）——唯一强制全量验证点。远端结果用 `tools/ci_check.sh <合并提交>` 按需现查（读该提交任务的 run 自身 `status`/`conclusion`，只呈报、不落盘），agent 开工先读 CI 状态的纪律不变，红未修不开新批。**绿须坐实**：零触发批的 run 照样建、照样 conclusion=success，但跑闸步是 `skipped`（run 55 实证）——一条闸都没跑不构成验证，现查件对此呈报「未验」（退出码 4），禁当绿证用；job 列表为空、取不到步级读数或工作流里没有跑闸步时呈报「不可判」，同样禁当绿证。CI 红态不回滚合并——修复走新开修复 worktree（`fix-<任务名>` 分支，非 iter 形免重塑免数卡），修复合回落地即再推再验追绿（追绿同链）。导入缓存刷新（.godot 不入 git 的在册坑）由工作流「导入缓存刷新」步接管。**合回零等待纪律（2026-11-04 用户裁，取代 2026-11-02 回执等待纪律）**：合回落地即向用户呈报本批总结并止回合——不挂后台轮询、不等回执、不被唤醒；CI 结论什么时候要看就现查一次（`tools/ci_check.sh`，run 那时早已落定，秒级）。退役缘由＝原轮询件把「commit status 离开 pending」当终局判据，会把 run 未落定期的尝试级失败写成终局红（run 37 实证：开跑 36 秒写红，该 run 三分半后 `conclusion=success`），且零触发批与 runner 排队必熬满超时再写红；同 commit 的多路轮询还重复覆写同一份判定。跑闸等一切分钟级跑批的等待纪律不变——后台运行，禁前台 sleep／轮询循环。 -4. **执法分层（全机械，零自觉依赖）**：①`.zcode/hooks/worktree-guard.sh`（PreToolUse，本机件不入 git）——agent 侧：主工作区 Edit/Write 与主区非 merge `git commit` 拦截（豁免 `.zcode/`、`.qoder/`；worktree 内目标快速放行；合并收尾提交凭 MERGE_HEAD 豁免）、`git commit --no-verify` 拦截（该旗标仅属用户）、iter 分支合回的一卡一提交数卡校验、规则闸（写 design/／game/ 前核对会话规约读取记录）。②post-merge 钩子——远端 CI 触发（只推送，不挂等待；仅主工作区，任务 worktree 内的合并不触发）。③git 层钩子＝合回链两件：pre-merge-commit（合回前置检查，2026-11-06 用户裁：主区 merge 落合并提交前自动跑 `tools/run_all_gates.sh --premerge`＝冒烟＋单元与集成全套件 4 分片，热导入缓存约 2 分钟；exit≠0 拦合并提交不拦合并动作——红态仓库停 MERGE_HEAD 态，修红 git commit 续合或 git merge --abort 放弃；快进合并不触发；--no-verify 可跳过且仅属用户）＋post-merge（远端 CI 触发，只推送，不挂等待）；合回链之外 git 层不设车道钩子——用户手工改动不受限；ZCode 层只约束 agent（子代理不经守卫层） +4. **执法分层（全机械，零自觉依赖）**：①`.zcode/hooks/worktree-guard.sh`（PreToolUse，本机件不入 git）——agent 侧：主工作区 Edit/Write 与主区非 merge `git commit` 拦截（豁免 `.zcode/`、`.qoder/`；worktree 内目标快速放行；合并收尾提交凭 MERGE_HEAD 豁免）、`git commit --no-verify` 拦截（该旗标仅属用户）、iter 分支合回的一卡一提交数卡校验、规则闸（写 design/／game/ 前核对会话规约读取记录）。②post-merge 钩子——远端 CI 触发（只推送，不挂等待；仅主工作区，任务 worktree 内的合并不触发）。③git 层钩子＝合回链两件：pre-merge-commit（合回前置检查，2026-11-06 用户裁：主区 merge 落合并提交前自动跑 `tools/run_all_gates.sh --premerge`＝冒烟＋单元全套件 4 分片，热导入缓存约 2 分钟；exit≠0 拦合并提交不拦合并动作——红态仓库停 MERGE_HEAD 态，修红 git commit 续合或 git merge --abort 放弃；快进合并不触发；--no-verify 可跳过且仅属用户）＋post-merge（远端 CI 触发，只推送，不挂等待）；合回链之外 git 层不设车道钩子——用户手工改动不受限；ZCode 层只约束 agent（子代理不经守卫层） 5. **会话单区（2026-11-04 用户裁）**：建区粒度＝回合——同一时刻每会话至多一个 worktree 在役；合入删区之前，会话内用户追加的事项一律并入在役区推进，禁为追加事项另开新区。区内全部事项完成后只做一次合入（一次 `git merge --no-ff`、post-merge 一次推送、远端 CI 只跑一次），追加事项在合入提交信息里分列；无改动需求的事项不建区。合回删区后用户再发令的事项＝新回合，另开新区（区名取该回合主任务名）。CI 红的 `fix-<任务名>` 修复区属同一回合的追绿延续，不另算新区。迭代实现批（iter 形分支）独占回合——其他类事项不得并入迭代区（合回守卫数卡校验本就拦未归卡提交），待其合回后按新回合另开。 ## 2. 五段流水线 @@ -23,8 +23,8 @@ |---|---|---|---| | 一·登记 | 无（闸管格式） | 待办清单条目 | 条目=标题登记元数据（日期/来源/可选优先级）＋正文四属性（实况/缺口/改动面/状态）；标题登记后不再变，正文随进程演进。格式与状态机权威=doc-conventions 第 12 节 | | 二·文档设计／美术设计 | doc-design（文档线，兼任反哺点写入）／asset-ingest（美术录入；样张素材由用户主导产出） | GDD 文档或 art-bible／过审样张素材；画面类需求另出预览图（文档线，2026-11-05 用户裁） | 用户提起或从待办清单取出；会话内进行、用户主导、禁无监管自跑；经用户点头确认心智一致才许写入文档；完成判据=待裁点清零，带未裁点的是讨论稿；设计线闭合凭据记入待办清单实况清单（文档线=文档路径+版本号，美术线=art-bible 条款版本）；缺哪条线写在缺口属性，闭合与否写在状态段。画面类需求（新增画面要素／布局／配色／动效等触碰画面呈现规格的改动）设计段先出预览图＝目标画面的 HTML/SVG 效果图（diagram-design 通道，AGENTS.md 图优先的同款载体），经用户人审通过才许进写卡段；预览图内嵌对应 ux/ 规格文档并随附像素级视觉判据句（§7 第 2 条同款写法）；缺陷修复以现行规格与在库基线为准，不触发新预览 | -| 三·写需求卡片 | req-card | 需求卡片 | 设计线闭合后用户发令；新玩法/新系统/新内容必须有设计定稿前置，例外=需求性工程条目（缺陷修复／重构等改游戏行为）凭实况里的证据指认跳过设计线；配套维护类（工程债/测试基建/工具维护，不动游戏行为）＝工程改动直改类，不走本段，由用户发令直改；卡片必经 grilling 多轮复核、零待裁点才成立；复核发现按四类去向处置（2026-11-05 用户立规，定义在 req-card 技能「复核发现四类分流」：自判＝查权威文档或查代码现状有唯一答案，复核者自己下结论改卡；补写＝卡里漏写，回炉补全；待裁＝几种做法都不违规且代价不同、影响玩法取向，才交用户；退回上游＝文档设计线未闭合、美术设计线未闭合、或架构与代码规范本身冲突，停笔退对应段）；成立凭据＝卡内「复核记录」节＋该节申报的复核报告路径，顺序未走完禁对用户称完成、禁落 commit（同 §1 第 2 条卡片复核前置判据）；写完在待办清单状态记「已写卡」，卡片路径与复核报告路径记入实况清单（防遗忘）；画面类需求卡片必引设计段已人审的预览图（验收判据的判据出处行锚指向 ux/ 内嵌预览节，test-conventions §8.3 锚口径不变） | -| 四·迭代编排 | iter-plan | roadmap 迭代行 | 编排五查：①每卡卡片文件存在 ②每卡设计闭合凭据齐（或需求性工程条目的证据指认）③估时与冻结线——所选卡估时按区间**中值**求和（单位工作日、写精确值不取整）：**卡片任何工作量均可编入**（2026-10-25 用户立：工作量限制属迭代层、非卡片层）；编入后迭代总量 <5 个工作日＝迭代行状态「冻结待凑批」、不可开工，凑批 ≥5 后由编排段改「待开工」（迭代体量偏好，2026-10-21 用户立、2026-10-25 改冻结制）；5–10 个工作日为常规区间；超过 10 个工作日须经用户确认（确认前呈报整批/拆批两案等裁，禁自行拆分或塞入），确认后迭代行随带日期特批标记；超过 20 个工作日禁止编（硬上限，用户确认也不放行，必须拆批）④每卡复核记录在位（2026-11-05 用户立规）——卡内有「复核记录」节、该节申报的复核报告文件在 `reports/` 盘上真实存在；缺则呈报退回写卡段，禁编入，本段不代跑复核也不代补记录（生效＝卡片文件名日期 ≥2026-11-06，旧卡不回头改）⑤写完 roadmap 行后跑流水线闸确认绿；编入未完成迭代，新开迭代行经用户确认 | +| 三·写需求卡片 | req-card | 需求卡片 | 设计线闭合后用户发令；新玩法/新系统/新内容必须有设计定稿前置，例外=需求性工程条目（缺陷修复／重构等改游戏行为）凭实况里的证据指认跳过设计线；配套维护类（工程债/测试基建/工具维护，不动游戏行为）＝工程改动直改类，不走本段，由用户发令直改；卡片必经 grilling 多轮复核、零待裁点才成立；复核发现按四类去向处置（2026-11-05 用户立规，定义在 req-card 技能「复核发现四类分流」：自判＝查权威文档或查代码现状有唯一答案，复核者自己下结论改卡；补写＝卡里漏写，回炉补全；待裁＝几种做法都不违规且代价不同、影响玩法取向，才交用户；退回上游＝文档设计线未闭合、美术设计线未闭合、或架构与代码规范本身冲突，停笔退对应段）；成立凭据＝卡内「复核记录」节（2026-11-06 用户裁：不另设复核报告文件），顺序未走完禁对用户称完成、禁落 commit（同 §1 第 2 条卡片复核前置判据）；写完在待办清单状态记「已写卡」，卡片路径记入实况清单（防遗忘）；画面类需求卡片必引设计段已人审的预览图（验收判据的判据出处行锚指向 ux/ 内嵌预览节，test-conventions §8.3 锚口径不变） | +| 四·迭代编排 | iter-plan | roadmap 迭代行 | 编排五查：①每卡卡片文件存在 ②每卡设计闭合凭据齐（或需求性工程条目的证据指认）③估时与冻结线——所选卡估时按区间**中值**求和（单位工作日、写精确值不取整）：**卡片任何工作量均可编入**（2026-10-25 用户立：工作量限制属迭代层、非卡片层）；编入后迭代总量 <5 个工作日＝迭代行状态「冻结待凑批」、不可开工，凑批 ≥5 后由编排段改「待开工」（迭代体量偏好，2026-10-21 用户立、2026-10-25 改冻结制）；5–10 个工作日为常规区间；超过 10 个工作日须经用户确认（确认前呈报整批/拆批两案等裁，禁自行拆分或塞入），确认后迭代行随带日期特批标记；超过 20 个工作日禁止编（硬上限，用户确认也不放行，必须拆批）④每卡复核记录在位（2026-11-05 用户立规；2026-11-06 用户裁凭据换代——复核凭据＝「复核记录」节自身，不另查报告文件）——卡内有「复核记录」节；缺节或节内任一条发现没有去向标记则呈报退回写卡段，禁编入，本段不代跑复核也不代补记录（生效＝卡片文件名日期 ≥2026-11-06，旧卡不回头改）⑤写完 roadmap 行后跑流水线闸确认绿；编入未完成迭代，新开迭代行经用户确认 | | 五·实现 | iter | 代码与配置，可运行的游戏 | 需求卡片永不单独施工，统一由用户指定迭代号触发（=U0 开工令），按 iter 技能与本文 §3 执行；**本段是代码实现批：禁写 `design/` 与根规则文件，产出物只落 `reports/`（见 §3 第 12 条）**；设计权威文档（GDD/art-bible）批内一律不更新；完成人闸=实机目检清单+实现决定记录写齐即完成批内义务；画面类需求实现批另按 test-conventions §8.2 黄金图基线冻结口径执行（实跑截图入基线前用户对照预览图确认一眼，此后渲染闸自动盯） | **实现段零裁断**：实现段的输入在编排段出口已锁死（卡片零待裁点＋设计闭合凭据齐＋编排五查过）。实现中冒出卡片没写清的分歧=上游缺陷——停该卡、待办清单状态回退＋缺口补记，退回上游；禁自答、禁内联提问求裁断；该卡停摆不阻塞同迭代其他卡。环境故障与测试红走异常分级（自救重试／记录继续／停机呈报）。代拍板白名单保留：授权发生在卡片审问阶段，实现只执行预授权；超白名单／超卡片明列范围事项记入实现报告「实现决定记录」节备案，不另立追认单。 diff --git a/design/engineering/test-conventions.md b/design/engineering/test-conventions.md index f8ef1ef2..0550d090 100644 --- a/design/engineering/test-conventions.md +++ b/design/engineering/test-conventions.md @@ -13,6 +13,20 @@ 核心层验收标准通过不算有测试：GDScript 编译不查字典字段与时序，呈现层错误只在运行时暴露。 测试必须证明功能可达（用户真的能用到）且行为正确（结果符合验收标准）。 +### 1.1 测试层三元组（2026-11-07 用户裁——测试层识别权威表） + +识别一个测试层靠三元组，不靠名字——**层级名只是代称**；名称与定义的登记面＝`design/gdd/术语表.md`，本表是识别判据的单点： + +| 层（代称） | 职责 | 触发时间点 | 覆盖面积 | +|---|---|---|---| +| 冒烟测试 | 真实开机路径存活检查——启动／加载表／进主屏，零逻辑判定 | 每次代码域跑批＋合回前置检查＋远端 CI（三件保险恒跑不降） | 最小：一条真实开机路径 | +| 单元测试 | 受控裸环境断言面：单机制契约＋跨系统真实路径闭环——不加载开机装配、手工构造注入实跑；闭环套件＝两以上真实系统手工装配×落盘往返，性质归属由各套件头注「跨系统面」句承载 | 同冒烟（恒跑；关联档选套件＝需求卡片申报∪diff 推导并集，横切回落全量） | 领域类原子行为＋跨系统接缝——不含开机装配与画面 | +| 系统测试 | 真实开机＋真实玩法路径行为断言（推理→战斗→结算→推进） | 同冒烟（恒跑） | 完整装配下的玩法旅程 | +| 场景探针 | 真实实例化场景＋真输入管线（合成输入事件走输入管线）的 UI 可达性／可见性／状态 | 代码域跑批（测量面批记 SKIP）＋远端 CI | 逐 UI 区域交互动线 | +| 渲染闸 | 窗口化真实渲染截图 vs 冻结基线图逐像素容差比对 | 代码域跑批（测量面批与 --quick 记 SKIP）＋远端 CI | 像素呈现（主题／素材／排版） | + +层级合并说明（2026-11-07 用户裁）：跨系统真实路径闭环套件归单元层承载，三套件实体在 `game/tests/unit/`；「集成测试／集成用例／集成层／集成侧／集成宿主／集成族」为退役词（术语表「退役词对照」；S11 注释面＋用语审计文档面双承接）。 + ## 2. 场景级探针标配 每新增一个可交互 UI 区域（视图/覆盖层/面板），必须配套场景级 headless 探针： @@ -29,7 +43,7 @@ ## 4. 验证时机（合回后远端 CI 制，2026-11-03 换代） -开发期义务＝`process-conventions.md` §4 改完即测铁规：本批新增/改动的验收测试自己跑绿、读数写进该步提交信息才算完成（卡内只测自己改的东西）。合回 merge 提交落笔前另有 pre-merge-commit 前置检查（2026-11-06 用户裁：冒烟＋单元与集成全套件 4 分片，约 2 分钟——当场拦截面，不落回执；细则见 process-conventions §1 第 4 条 ③）。全量验证归合回后的远端 CI：git merge 合回 master 落地后 post-merge 钩子推送 origin master，远端按改动域分流跑 `tools/run_all_gates.sh`（游戏码批＝不带参数档两域全量、单元与集成测试全套件——跨卡触面与关联档选测的盲区由全量兜底；文档批＝文档域秒级闸；分流算法单点＝`tools/ci/domain_route.sh`），远端结果用 `tools/ci_check.sh <合并提交>` 按需现查（读 run 自身 `status`/`conclusion`，只呈报、不落盘——合回不等待、不唤醒，process-conventions §1 第 3 条）；CI 红态下修复合回落地即再推再验追绿（修复走新开 `fix-<任务名>` 修复 worktree，process-conventions §1）。同一份字节禁止第二次人手跑。该脚本是全部验证闸的唯一入口与唯一清单，域划分与选闸算法只写在脚本里，本文禁另列闸件清单。 +开发期义务＝`process-conventions.md` §4 改完即测铁规：本批新增/改动的验收测试自己跑绿、读数写进该步提交信息才算完成（卡内只测自己改的东西）。合回 merge 提交落笔前另有 pre-merge-commit 前置检查（2026-11-06 用户裁：冒烟＋单元全套件 4 分片，约 2 分钟——当场拦截面，不落回执；细则见 process-conventions §1 第 4 条 ③）。全量验证归合回后的远端 CI：git merge 合回 master 落地后 post-merge 钩子推送 origin master，远端按改动域分流跑 `tools/run_all_gates.sh`（游戏码批＝不带参数档两域全量、单元测试全套件——跨卡触面与关联档选测的盲区由全量兜底；文档批＝文档域秒级闸；分流算法单点＝`tools/ci/domain_route.sh`），远端结果用 `tools/ci_check.sh <合并提交>` 按需现查（读 run 自身 `status`/`conclusion`，只呈报、不落盘——合回不等待、不唤醒，process-conventions §1 第 3 条）；CI 红态下修复合回落地即再推再验追绿（修复走新开 `fix-<任务名>` 修复 worktree，process-conventions §1）。同一份字节禁止第二次人手跑。该脚本是全部验证闸的唯一入口与唯一清单，域划分与选闸算法只写在脚本里，本文禁另列闸件清单。 行为探针使用随机化玩家行为（封印/停手/刷新/无效点击）——自动玩家不做的动作就是测试盲区。 ## 5. 测试函数怎么写——验收清单条目的落码规范 @@ -81,7 +95,7 @@ - **单元**：不依赖场景树和真实宿主的纯逻辑；测试从领域类的对外方法进出，断言钉对外可观测面（返回值／信号／查询接口／落盘内容）。内部字段直查＝受控例外：仅当该行为没有公开可观测面可钉时允许，对照表该行注明理由；存量不回头清扫，被批次触碰时顺带换代。探针直读视口承载子件结构（画布取视口首子件、渐隐带两片与平移提示子件按名取）属此类——断言对象即承载结构本身，无公开可观测面可钉，理由随对照表行申报。 - **接口**：模块边界的公开契约——数据表加载、存档与断点、事件载荷、命令接口；测试从公开入口进出。接口级断言随单元套件落（`unit/contracts/`），不另设承载目录。 -- **集成**：跨宿主的接线、持久、生命周期——例如 LevelRunner 把 level_counters 传给 BattleOrchestrator、两场战斗共享同一个桶、断点续玩；测试必须实例化真实宿主链，禁止用裸 EffectEngine 代替。 +- **跨宿主**：跨宿主的接线、持久、生命周期——例如 LevelRunner 把 level_counters 传给 BattleOrchestrator、两场战斗共享同一个桶、断点续玩；测试必须实例化真实宿主链，禁止用裸 EffectEngine 代替。断言载体归单元层跨系统闭环套件（§1.1 三元组表），验收入口不变。 - **探针/golden**：玩家可达性与观感；真实实例化场景、驱动真实输入。 - **golden 测试项扩项（2026-11-05 立）**：触碰画面呈现规格的需求批（新增画面要素／布局／配色／动效；判据＝设计段出了预览图），实现段把该画面纳入渲染闸机器面：截图采集清单扩项＋实跑截图冻结进 `game/tests/golden/`（基线属入库测试资产，render_gate.sh 在册例外）。黄金图＝游戏真实渲染截屏冻结的逐像素基准，比对器与容差口径见 render_gate.sh 头注释（脚本即清单，本文不另列）。基线冻结（新建与换代同口径）＝用户对照设计段预览图确认后执行，触发原因写进当批提交说明（`tools/golden_baseline_refresh.sh` 现役义务）；此后渲染闸逐像素自动盯、零人工。预览图（HTML/SVG 效果图）与引擎渲染是两套管线，禁直接充当比对基线——预览图只作人审参照与验收判据句的出处（判据出处行锚指向 ux/ 内嵌预览节）；缺陷修复以现行规格与在库基线为准，不触发新预览。 @@ -112,7 +126,7 @@ **新增 core 件的覆盖登记义务（2026-11-03 架构审查 P1 余项裁）**：拆件或重构产出的新 core 文件不触发 process-conventions §3 第 6 条「新功能必配新测试」（那条只管新增玩法/机制），因此单由本条承接——新 core 件要么被 `game/tests/` 某套件按文件名或 `class_name` 点名，要么在承接它的能力行「代表用例」里申报「经宿主链覆盖（宿主＝<件>）」；两者都无＝批末收尾核对时补登。本条**不是覆盖率要求**，与 §7「覆盖率不是目标」同轨：登记的是能力义务的归属，不做文件计数——「每个 core 件必须被点名一次」的机器闸已裁否（它逼出为点名而点名的空套件，且与 §7 正面冲突）。落笔面沿用现行分工：申报行由写卡段入能力清单（实现批禁写该文件），核对归批末收尾提交。 -**退役对账义务（2026-11-05 立）**：需求卡片退役（吸收即死）时，其对照表每行的验收意图必须已被承接——承接形态＝能力清单行（能力＋真实入口＋代表用例）或已落地的断言；退役后无承接＝该能力的规格判据断链，收尾核对判红。机检＝`tools/capability_audit.py`（套件→能力行反向覆盖＋断言链核验）。先例教训：营地图批卡片退役后，大门判据（`design/gdd/ux/camp.md:16`）无任何活面承接，探针 emit 断言悬空假绿——规格在、链接断。 +**退役对账义务（2026-11-05 立）**：需求卡片退役（吸收即死）时，其对照表每行的验收意图必须已被承接——承接形态＝能力清单行（能力＋真实入口＋代表用例）或已落地的断言；退役后无承接＝该能力的规格判据断链，收尾核对判红。机检＝`tools/capability_audit.py`（套件→能力行反向覆盖＋断言链核验）。先例教训：营地图批卡片退役后，大门判据（`design/ux/camp.md:16`）无任何活面承接，探针 emit 断言悬空假绿——规格在、链接断。 ### 8.4 真实入口断言（验收闭合的主判据） diff --git a/design/gdd/02-系统清单.md b/design/gdd/02-系统清单.md index 48bce357..bb5a925b 100644 --- a/design/gdd/02-系统清单.md +++ b/design/gdd/02-系统清单.md @@ -69,7 +69,7 @@ | `教学引导.md` | 新手教学与提示 | 范围草案·待设计 | | `设置与本地化.md` | 设置项与多语言 | 范围草案·待设计 | -## ux/（战斗画面与交互规格，`ux/`） +## ux/（战斗画面与交互规格，`design/ux/`——与 gdd/ 同级的呈现实现设计规格层） | 文件 | 一句话概要 | 状态 | |---|---|---| diff --git a/design/gdd/03-内容规模.md b/design/gdd/03-内容规模.md index 800a778d..2e76cdcf 100644 --- a/design/gdd/03-内容规模.md +++ b/design/gdd/03-内容规模.md @@ -63,7 +63,7 @@ MVP 不加新状态；扩容走 `status_effects.tres` 加行 + [增益状态](sy 垂直切片阶段明确砍掉或推迟的内容，写在这里防止回潮： - 更多关卡（N>3）——第三关已按扩展批流程落地（行集）；三关正式序列已生效，唯一试玩入口 = 完整冒险 -- 精英节点与词缀系统——只预留了字段位，不定义语义（精英怪**设定**已登记预留——同立绘+附加特征标记+数值更强、钥石掉 1 个预留；实装随怪物批） +- 精英节点与词缀系统——精英怪本体已落敌人表（行类 elite＋池继承基础池加附加技，首只＝地精精英），精英节点与投放仍未接线；词缀系统未设计 - 地形变异扩展内容——首批四类型已落地，反制道具与全局作用域排 Alpha - 道具/增益之间的组合协同（遗物式联动） - 战后自动回复——回复只有道具与恢复点两个来源 diff --git a/design/gdd/08-Alpha版本标准.md b/design/gdd/08-Alpha版本标准.md index 06ca47b4..144eff1c 100644 --- a/design/gdd/08-Alpha版本标准.md +++ b/design/gdd/08-Alpha版本标准.md @@ -103,15 +103,15 @@ Alpha 内以玩法循环本身的内容与表现为主（棋盘、关卡、战 | 主菜单 | —— | 在役（三入口：进入存档／设置／退出游戏——入口拓扑=进入存档→选档界面→进档/新档→营地覆盖层→营地场景图与生涯笔记本） | | 开始覆盖层 | —— | 在役 | | 选档界面（3 存档位） | —— | 在役（空槽新档/有档进档/删档二次确认＋摘要三项） | -| 营地（天赋树 / 锻造工坊 / 秘宝匣 / 图鉴） | [camp](ux/camp.md) | 在役（场景图＋七物件点选＋Esc 浮窗与顶栏；五功能页呈现＝居中定尺寸功能窗口、场景根留底、窗内滚动） | -| 营地交互重做（五卡：存档制数据层／主菜单三入口／选档界面／营地场景图／Esc 浮窗与营地顶栏） | [camp](ux/camp.md) | 在役（五卡全部落地，2026-10-21 用户裁整体列入 Alpha；沿革查 git 提交史。出口＝五卡各自验收标准通过＋营地屏用户目检〔登记体验验证清单 ㊺〕） | +| 营地（天赋树 / 锻造工坊 / 秘宝匣 / 图鉴） | [camp](../ux/camp.md) | 在役（场景图＋七物件点选＋Esc 浮窗与顶栏；五功能页呈现＝居中定尺寸功能窗口、场景根留底、窗内滚动） | +| 营地交互重做（五卡：存档制数据层／主菜单三入口／选档界面／营地场景图／Esc 浮窗与营地顶栏） | [camp](../ux/camp.md) | 在役（五卡全部落地，2026-10-21 用户裁整体列入 Alpha；沿革查 git 提交史。出口＝五卡各自验收标准通过＋营地屏用户目检〔登记体验验证清单 ㊺〕） | | 生涯页 | [生涯](systems/跨局循环/生涯.md) | 在役（期一） | -| 关卡地图屏 | [level-map](ux/level-map.md) | 在役 | -| 战斗屏 | [battle](ux/battle.md) | 在役 | -| 战斗结算总结框 | [settlement-summary](ux/settlement-summary.md) | 在役 | -| 关卡结算屏 | [level-clear](ux/level-clear.md) | 在役 | -| 三选一（奖励节点 / 关卡完成） | [node-reward](ux/node-reward.md) | 在役（两渠道均三选一停点：关卡完成与奖励节点各停一次，奖励节点经兑付拉起开三选一） | -| 商店 | [shop](ux/shop.md) | 在役 | +| 关卡地图屏 | [level-map](../ux/level-map.md) | 在役 | +| 战斗屏 | [battle](../ux/battle.md) | 在役 | +| 战斗结算总结框 | [settlement-summary](../ux/settlement-summary.md) | 在役 | +| 关卡结算屏 | [level-clear](../ux/level-clear.md) | 在役 | +| 三选一（奖励节点 / 关卡完成） | [node-reward](../ux/node-reward.md) | 在役（两渠道均三选一停点：关卡完成与奖励节点各停一次，奖励节点经兑付拉起开三选一） | +| 商店 | [shop](../ux/shop.md) | 在役 | | 状态面板（局内） | [元进度](systems/跨局循环/元进度.md)（「解锁界面：双入口框架」节） | 在役 | | 冒险终局面板 | —— | 在役 | | 图例面板 | —— | 在役 | @@ -147,12 +147,12 @@ Alpha 内以玩法循环本身的内容与表现为主（棋盘、关卡、战 | 棋盘瓦片与格面资源图标 | [美术圣经](../art/art-bible.md) | 在役 | | 未开格类型微光（五组色相＋明度档） | [HUD框架](systems/表现与支撑/HUD框架.md) | 在役（明度档 provisional 值登记见 art-bible 的 git 提交史；观感复核已随战斗一屏样张过闸完成——用户实机目检核销，沿革查 git 提交史） | | 棋盘观感（第二 / 三关亮度与对比度） | [待办清单](../../待办清单.md) | 待做（开工前置＝先做素材轴／UI 轴对照截图定性，再按定轴修复；旧卡 v1.4 存 reports/ 作素材、非已写卡状态，重启须重新立卡；出口＝用户实机目检第二、三关不再判「看着费劲」） | -| 立绘显示清晰度（原稿分辨率＋三档显示） | [角色设计](../art/character-design.md) | 在役（原稿分辨率入包禁降采样、显示按三档绝对高 96/144/188 缩放、现有形象即终稿；定值单点=art-bible §8.2；实机目检清晰度与同屏体量顺序登记体验验证清单 ㊻） | +| 立绘显示清晰度（原稿分辨率＋三档显示） | [角色设计](../art/character-design.md) | 在役（原稿分辨率入包禁降采样、显示按三档绝对高缩放、现有形象即终稿；定值单点=art-bible §8.2（档值定值面＝站桩守门测试）；实机目检清晰度与同屏体量顺序登记体验验证清单 ㊻） | | 敌人立绘（全敌种） | [角色设计](../art/character-design.md) | 在役 | | 主角立绘三态 | [角色设计](../art/character-design.md) | 在役 | | 状态图标 | [美术圣经](../art/art-bible.md) | 在役 | | 战斗演出链（弹道 / 受击 / 血条 / 灰化） | [战斗表现](systems/战斗循环/战斗表现.md) | 在役 | -| 逐行结算排播 | [settlement-summary](ux/settlement-summary.md) | 在役 | +| 逐行结算排播 | [settlement-summary](../ux/settlement-summary.md) | 在役 | | 减动效开关 | [设置与本地化](systems/表现与支撑/设置与本地化.md) | 在役 | | 全局纹理过滤设为邻近采样 | [待办清单](../../待办清单.md) | 在役（default_texture_filter=0＋平滑渐变件三处显式 LINEAR 白名单，翻转面全枚举闭合） | | UI 字体（全局像素字，Fusion Pixel 单套单字重） | [美术圣经](../art/art-bible.md) §7.4 | 在役（现状即终稿——拉丁沿用自带字形不另接专件、不上第二字重；信息层级手段＝字号档差＋墨色深浅） | diff --git a/design/gdd/systems/冒险循环/关卡节点图生成.md b/design/gdd/systems/冒险循环/关卡节点图生成.md index 15ef939b..2ccd0237 100644 --- a/design/gdd/systems/冒险循环/关卡节点图生成.md +++ b/design/gdd/systems/冒险循环/关卡节点图生成.md @@ -74,7 +74,7 @@ 每关一套参数档（L1/L2/L3），生成器只吃参数档、不认关卡号。生长曲线：层高、宽度、节点总数、路径长度逐关递增且增幅变大；决策点密度逐关递增；第一关即含岔口——第一关也要有选择。单链是分支密度取下限的合法退化形态，不作为三关参数档的取值。 -图规模无呈现侧上限：关卡画面为卷轴视口呈现，画布随图生长、屏为窗口（呈现规格归 [level-map](../../ux/level-map.md)）；规模由参数档与生长曲线约束，参数档给不出合法图即致命中止。 +图规模无呈现侧上限：关卡画面为卷轴视口呈现，画布随图生长、屏为窗口（呈现规格归 [level-map](../../../ux/level-map.md)）；规模由参数档与生长曲线约束，参数档给不出合法图即致命中止。 ### 节点类型配比：类型分布怎么掷、内容归谁 diff --git a/design/gdd/systems/冒险循环/关卡节点地图.md b/design/gdd/systems/冒险循环/关卡节点地图.md index f6cdf6e4..1679470b 100644 --- a/design/gdd/systems/冒险循环/关卡节点地图.md +++ b/design/gdd/systems/冒险循环/关卡节点地图.md @@ -64,9 +64,9 @@ 每个节点在图上有**节点深度**（本文含义：自入口沿路走到该节点的最长路径步数；多入口时取距任一入口的最长路径），用来当战斗的定位地址——遭遇坐标＝关卡序号＋节点深度，敌人表按**深度带**（深度区间）配池，寻址语义见[敌人系统](../战斗循环/敌人系统.md)。不用最短路径：合流节点或多入口图上取最短，会让某些出边指向深度不增甚至更浅的节点，破坏「连线只朝前进方向」的无环判据。"最深处是关底"的直感由深度承载：终点恒在各路径最深处。单链（每步只有一条连线）是合法退化形态，节点深度等于它前面走过的战斗场数；三关参数档都含岔口，第一关不再是单链。图的来源见[关卡节点图生成](关卡节点图生成.md)。 -呈现侧口径（2026-09-17 用户拍板）：节点图的画面表达走**方块地牢观感**——节点画成地牢房间的方块、连线画成通道——但逻辑拓扑就是本文的节点图，不产生任何额外选路或探索语义。关卡画面本体即节点链进度的呈现载体（选路覆盖层的常驻形态，节点态直接读图：已过暗金 / 当前金 / 候选下一跳通道亮金 / Boss 紫赤描边（紫赤＋深墨环，视觉定稿见 [level-map](../../ux/level-map.md)）），不另设进度条组件；视觉规格归 [HUD 框架](../表现与支撑/HUD框架.md)。 +呈现侧口径（2026-09-17 用户拍板）：节点图的画面表达走**方块地牢观感**——节点画成地牢房间的方块、连线画成通道——但逻辑拓扑就是本文的节点图，不产生任何额外选路或探索语义。关卡画面本体即节点链进度的呈现载体（选路覆盖层的常驻形态，节点态直接读图：已过暗金 / 当前金 / 候选下一跳通道亮金 / Boss 紫赤描边（紫赤＋深墨环，视觉定稿见 [level-map](../../../ux/level-map.md)）），不另设进度条组件；视觉规格归 [HUD 框架](../表现与支撑/HUD框架.md)。 -**商店覆盖层呈现**（呈现 spec：[design/gdd/ux/shop.md](../../ux/shop.md) v1.0；pool 模式货架面=共享池三选一同构卡〔进店抽 3/买 1 全重抽/空架售罄态〕，与三选一奖励同一交互语言；legacy 固定三件面随对照模式保留。**库存余量不呈现**（2026-10-04 用户裁）——货架卡不带「库存余 N/∞」字样，库存语义仍在共享池令牌库、只是不呈现）：兑付 = 打开商店覆盖层（模态）——货架卡陈列、GP 余额读数、购买/离开；离开后兑付确认回选路。本节锁编排面（何时开/何时关/回选路），呈现细节归 spec；定价数值归[难度曲线与Boss](难度曲线与Boss.md)（shop.tres）。 +**商店覆盖层呈现**（呈现 spec：[design/ux/shop.md](../../../ux/shop.md) v1.0；pool 模式货架面=共享池三选一同构卡〔进店抽 3/买 1 全重抽/空架售罄态〕，与三选一奖励同一交互语言；legacy 固定三件面随对照模式保留。**库存余量不呈现**（2026-10-04 用户裁）——货架卡不带「库存余 N/∞」字样，库存语义仍在共享池令牌库、只是不呈现）：兑付 = 打开商店覆盖层（模态）——货架卡陈列、GP 余额读数、购买/离开；离开后兑付确认回选路。本节锁编排面（何时开/何时关/回选路），呈现细节归 spec；定价数值归[难度曲线与Boss](难度曲线与Boss.md)（shop.tres）。 ### 行进与选路：兑付后确认，选路就是行进 @@ -85,7 +85,7 @@ | 纪律 | 内容 | |---|---| -| 兑付后确认 | 到达节点立即兑付，不设"进入前确认"步；兑付反馈呈现完，玩家确认才回图。战斗节点的确认挂在战斗总结结算上（呈现 spec：design/gdd/ux/settlement-summary.md），奖励/恢复节点挂在兑付反馈覆盖层上，商店节点挂在商店覆盖层的离开动作上——复用既有呈现位，零新增交互范式 | +| 兑付后确认 | 到达节点立即兑付，不设"进入前确认"步；兑付反馈呈现完，玩家确认才回图。战斗节点的确认挂在战斗总结结算上（呈现 spec：design/ux/settlement-summary.md），奖励/恢复节点挂在兑付反馈覆盖层上，商店节点挂在商店覆盖层的离开动作上——复用既有呈现位，零新增交互范式 | | 零自动推进 | 确认之后回到关卡画面的选路口：岔路口玩家选一条连线，单链路口确认"继续"。选了才走；不选就停在图上 | Boss 兑付（胜利或英雄死亡）触发关卡收束点，此后不再有选路——关卡已定局，后续流程归冒险结构。 @@ -123,7 +123,7 @@ Boss 兑付（胜利或英雄死亡）触发关卡收束点，此后不再有选 第二关的"新内容 = 既有池新技能"（技能池构成已定稿入[敌人系统](../战斗循环/敌人系统.md)技能池节）投放时，改的是战斗侧行里引用的技能池内容——节点图结构原样不动，本文无需为投放留任何新结构位。 -**节点奖励 = 提升三选一（用户 2026-10-01 拍板：与通关三选一共享同池）**：奖励节点到达即开三选一（呈现 = 提升三选一覆盖层共用面，spec：[node-reward.md](../../ux/node-reward.md) v2.0）——从提升池七种（攻击/生命上限/护甲/GP 袋/行动点件/恢复件/刷新件）按同一令牌库洗牌不放回抽 3（同 kind 去重、同一封闭随机流），玩家点选一件兑付（选中踢池、未选回池；秘宝件已出池，满位替换子交互随之不再触发）。件获取次数计数与令牌库为冒险级单例——两渠道同一令牌库合计消耗。「池空直通」为合法态——池耗即枯竭，空库 = 零候选合法态直通（见[冒险结构](冒险结构.md)令牌池节）。 +**节点奖励 = 提升三选一（用户 2026-10-01 拍板：与通关三选一共享同池）**：奖励节点到达即开三选一（呈现 = 提升三选一覆盖层共用面，spec：[node-reward.md](../../../ux/node-reward.md) v2.0）——从提升池七种（攻击/生命上限/护甲/GP 袋/行动点件/恢复件/刷新件）按同一令牌库洗牌不放回抽 3（同 kind 去重、同一封闭随机流），玩家点选一件兑付（选中踢池、未选回池；秘宝件已出池，满位替换子交互随之不再触发）。件获取次数计数与令牌库为冒险级单例——两渠道同一令牌库合计消耗。「池空直通」为合法态——池耗即枯竭，空库 = 零候选合法态直通（见[冒险结构](冒险结构.md)令牌池节）。 ### 关卡收束点：先清库、后宣布 diff --git a/design/gdd/systems/冒险循环/冒险结构.md b/design/gdd/systems/冒险循环/冒险结构.md index 0c79e7b0..56251691 100644 --- a/design/gdd/systems/冒险循环/冒险结构.md +++ b/design/gdd/systems/冒险循环/冒险结构.md @@ -35,7 +35,7 @@ | 节点奖励件的分类与凭证定义、池结构与抽取机制（案D——共享池库存仍归本文） | [奇物](奇物.md) | | 关卡完成率带、敌我数值与 Boss 设计 | [难度曲线与Boss](难度曲线与Boss.md) | | 钥石与跨局成长 | [元进度](../跨局循环/元进度.md) | -| 冒险总结结算（呈现摘要五件事；呈现 spec：design/gdd/ux/settlement-summary.md）与关卡推进指示 | [HUD框架](../表现与支撑/HUD框架.md) | +| 冒险总结结算（呈现摘要五件事；呈现 spec：design/ux/settlement-summary.md）与关卡推进指示 | [HUD框架](../表现与支撑/HUD框架.md) | ## 在核心循环中的位置 diff --git a/design/gdd/systems/冒险循环/奇物.md b/design/gdd/systems/冒险循环/奇物.md index 9c84e938..91e395b3 100644 --- a/design/gdd/systems/冒险循环/奇物.md +++ b/design/gdd/systems/冒险循环/奇物.md @@ -281,7 +281,7 @@ **两层是两件事，别混**： - **命名是本节的规矩**——三个分类各有一个专名，文档、代码词族、帮百科一律用它。指代某个分类时直接说「专长」，不说「机制类」「专长那一类」。 -- **呈现是另一件事**（归 [battle](../../ux/battle.md) 与 [node-reward](../../ux/node-reward.md)，本节不裁决）：玩家看到某件奇物时，卡面只写**这件东西的名字与效果**，不附带它的分类。玩家可以从效果反推它属于哪一类，但界面不替他说破。 +- **呈现是另一件事**（归 [battle](../../../ux/battle.md) 与 [node-reward](../../../ux/node-reward.md)，本节不裁决）：玩家看到某件奇物时，卡面只写**这件东西的名字与效果**，不附带它的分类。玩家可以从效果反推它属于哪一类，但界面不替他说破。 **为什么两层都要有**：分类名在卡面上不出现，不等于玩家对它没有概念——帮助手册、百科条目、成就名称三处一定会用到它（「首次集齐 4 件专长」「三件属性值提升」），效果描述里出现指代时也需要名字（如「本项属专长」类归类指代）。所以它必须是一个**玩家读得懂、读一遍就懂**的正式名词，不能是内部描述或自造词。 diff --git a/design/gdd/systems/冒险循环/难度曲线与Boss.md b/design/gdd/systems/冒险循环/难度曲线与Boss.md index e465f2dd..18f3b352 100644 --- a/design/gdd/systems/冒险循环/难度曲线与Boss.md +++ b/design/gdd/systems/冒险循环/难度曲线与Boss.md @@ -1,7 +1,7 @@ # 难度曲线与Boss > 一句话：难度曲线、期望值带与 Boss 设计 -> 状态：已定稿；现行为 v1.5 +> 状态：已定稿；现行为 v1.6 ## 设计目的 @@ -55,7 +55,7 @@ |---|---|---| | 关间台阶（关卡序号） | 每关至少投放一项新内容（新敌种或既有池新技能），加基准数值跳升 | 台阶必须能归因到看得见的变化，不是纯数字膨胀；投放断档是内容生产缺口，调参修补不了 | | 关内坡度（节点深度） | 同敌种数值平缓上移，深度也可表达为敌人成群 | 数量是比单体质变更优先的深度表达：保持技能池 EV 读数不变（权重即旋钮、EV 重锚顺带登记）、总量受控 | -| Boss 与精英修饰（预留第三轴） | Boss 走最深深度直填行；精英只有字段命名空间预留 | Boss 不走修饰表；修饰乘数表 MVP 为空表、零行为，首个使用场景 = 精英节点（随[关卡节点地图](关卡节点地图.md)定稿联动）；数值所有权在本系统，[棋盘生成](../排雷循环/棋盘生成.md)只按表生成。精英怪设定已登记预留（与其他普通小怪同一立绘 + 附加特征标记 + 数值更强；视觉特征三件 = 名称前后缀「精英·」+ 底座光环 + 描边变色，色板合规与样张闸义务随怪物设定批实装） | +| Boss 与精英修饰（预留第三轴） | Boss 走最深深度直填行；精英怪本体走敌人表精英行（独立行＋池继承附加，语义见[敌人系统](../战斗循环/敌人系统.md)「精英行」节），精英节点修饰只有字段命名空间预留 | Boss 不走修饰表；修饰乘数表 MVP 为空表、零行为，首个使用场景 = 精英节点（随[关卡节点地图](关卡节点地图.md)定稿联动）；数值所有权在本系统（含精英行数值与附加技权重），[棋盘生成](../排雷循环/棋盘生成.md)只按表生成。精英怪设定：与其他普通小怪同一立绘 + 附加特征标记 + 数值更强；视觉特征三件 = 名称前缀「精英·」（由精英行名字行值承载）+ 底座光环 + 描边变色，后两件的色板合规与样张闸义务随怪物设定批实装 | **结论**：关内坡度 = 每深一档同敌种基准上移，或按"深度也可表达为敌人成群"改由数量承载——单体生命随深度的具体走向以 `enemy.tres` 行值为准（数量优先于单体；s_hp 线性式为建模工具，现行行值不承诺随深度单调上移）；关间台阶 = 相邻关同敌种基准乘 1.3–1.6（域语义如上；s_hp / k_L 现行行值读 `enemy.tres`，取值域归敌人表字段定义）。 diff --git a/design/gdd/systems/战斗循环/战斗表现.md b/design/gdd/systems/战斗循环/战斗表现.md index 0bb2a95c..95f26517 100644 --- a/design/gdd/systems/战斗循环/战斗表现.md +++ b/design/gdd/systems/战斗循环/战斗表现.md @@ -13,7 +13,7 @@ ## 系统范围 -边界这样划：战斗屏上"发生什么、摆在哪里、是什么意思"已经由两份现行文档定稿——屏级呈现形态归 [战斗屏 UX 规格 battle.md](../../ux/battle.md)，视觉基调与剪影色彩归 [美术圣经 art-bible](../../../art/art-bible.md)。本文只负责"这些东西怎么动"，而且是排期靠后的打磨项（见 [不做清单](../../05-不做清单.md)：战斗动画演出是 MVP 内的打磨项，一律排后）。 +边界这样划：战斗屏上"发生什么、摆在哪里、是什么意思"已经由两份现行文档定稿——屏级呈现形态归 [战斗屏 UX 规格 battle.md](../../../ux/battle.md)，视觉基调与剪影色彩归 [美术圣经 art-bible](../../../art/art-bible.md)。本文只负责"这些东西怎么动"，而且是排期靠后的打磨项（见 [不做清单](../../05-不做清单.md)：战斗动画演出是 MVP 内的打磨项，一律排后）。 负责： @@ -27,7 +27,7 @@ | 不负责 | 归谁 | |---|---| -| 屏级呈现形态与呈现语义（四区布局、敌人呈现〔站桩形态〕、明细带、高光行） | [battle.md](../../ux/battle.md) 与 [HUD 框架](../表现与支撑/HUD框架.md)，本文只引用 | +| 屏级呈现形态与呈现语义（四区布局、敌人呈现〔站桩形态〕、明细带、高光行） | [battle.md](../../../ux/battle.md) 与 [HUD 框架](../表现与支撑/HUD框架.md)，本文只引用 | | 视觉基调、剪影哲学、色彩与图标键契约 | [art-bible](../../../art/art-bible.md)，本文只引用 | | 结算逻辑与逐行流水本身 | [战斗结算](战斗结算.md) | | 敌种视觉状态的数据面（哪个敌种有几态、什么姿态） | [敌人系统](敌人系统.md) | @@ -48,7 +48,7 @@ ### 不另起场景：在既有呈现上叠加动画密度 -战斗屏是挖掘与结算两种形态共用的同一张屏：常驻双舞台（白话：战斗画面与扫雷图同屏常驻，像同一块屏上的两个舞台），结算期不切换场景，裁决与理由见 [battle.md 布局决策 1](../../ux/battle.md)。所以战斗表现的工作不是另做一个战斗场景，而是在既有呈现上叠加动画密度与演出——这是本系统范围边界的第一条。 +战斗屏是挖掘与结算两种形态共用的同一张屏：常驻双舞台（白话：战斗画面与扫雷图同屏常驻，像同一块屏上的两个舞台），结算期不切换场景，裁决与理由见 [battle.md 布局决策 1](../../../ux/battle.md)。所以战斗表现的工作不是另做一个战斗场景，而是在既有呈现上叠加动画密度与演出——这是本系统范围边界的第一条。 "发生什么"与"怎么动"因此分了工：敌人死亡是血条归零后灰化加碎裂退场、禁止瞬间消失，结算明细带逐行滚动，完美封印与封印标中有高光行强调——这些呈现语义已由 battle.md 与 HUD 框架定稿，本文不复述。本文将来承接的只是其上的动画密度：受击反馈、弹道、退场动画等类别。 @@ -80,7 +80,7 @@ 样张是前置美术测试的判定物；本节把"怎么算过"在测试组织前写成文，避免临场现定标准。成文做法参照 [art-bible](../../../art/art-bible.md) §1.4 格子样张测试（内容清单、按序验收项、判定与回退），判据全部落到已冻结的现行口径上——本节不定任何新的视觉参数。 -样张内容清单（一组齐备，缺项即无效）：按 [battle.md 布局决策 1](../../ux/battle.md) 的常驻双舞台四区布局整屏出样；角色剪影按棋盘格、结算明细带、战斗舞台三个语境同图摆放；~~敌人卡两候选形态对照（卡片式与站桩式各一版，其余内容不变）~~——**本项已完成（全站桩定稿、卡片式退役），正式样张按站桩形态单版出样即可**；受击、退场、高光兑现三组动画关键帧条（每组至少起、中、末三帧）；敌人姿态精灵与数字、封印印记、小人同格叠放的遮挡对照组至少一组。 +样张内容清单（一组齐备，缺项即无效）：按 [battle.md 布局决策 1](../../../ux/battle.md) 的常驻双舞台四区布局整屏出样；角色剪影按棋盘格、结算明细带、战斗舞台三个语境同图摆放；~~敌人卡两候选形态对照（卡片式与站桩式各一版，其余内容不变）~~——**本项已完成（全站桩定稿、卡片式退役），正式样张按站桩形态单版出样即可**；受击、退场、高光兑现三组动画关键帧条（每组至少起、中、末三帧）；敌人姿态精灵与数字、封印印记、小人同格叠放的遮挡对照组至少一组。 验收项按序判定，第一项不过 = 整张否决（继承格子样张"数字可读性定风格"的次序）： @@ -118,7 +118,7 @@ | 上游 | [HUD 框架](../表现与支撑/HUD框架.md) | 四区布局、战斗画面区（四区中的 B 区）演出区结构、敌人呈现（站桩形态）与明细带呈现语义——本文在其上叠加密度 | | 上游 | [敌人系统](敌人系统.md) | 资产需求下限三类与敌种姿态数据面——数据已锁，本文出终稿；另登记一项随样张一并裁决的事项：敌人层绘制优先级的插入位置 | | 上游 | [art-bible](../../../art/art-bible.md)（现行权威） | 剪影、色彩、图标键契约、各阶段氛围——表现侧约束 | -| 上游 | [battle.md](../../ux/battle.md)（现行权威） | 屏级呈现形态与呈现语义 | +| 上游 | [battle.md](../../../ux/battle.md)（现行权威） | 屏级呈现形态与呈现语义 | | 协作 | [音频](../表现与支撑/音频.md) | 坍塌显形动画与音效方向配对登记，将来对位设计（挂点未定） | ## P0 最小闭环 diff --git a/design/gdd/systems/战斗循环/敌人系统.md b/design/gdd/systems/战斗循环/敌人系统.md index ca486875..a2b474a4 100644 --- a/design/gdd/systems/战斗循环/敌人系统.md +++ b/design/gdd/systems/战斗循环/敌人系统.md @@ -1,7 +1,7 @@ # 敌人系统 > 一句话：敌人数据、技能池出招、意图呈现 -> 状态：已定稿；现行为 v1.8 +> 状态：已定稿；现行为 v1.9 ## 设计目的 @@ -138,6 +138,20 @@ Boss 专属身份 = 专属池承载：独占技能 + 权重轮廓（**技能错 举证：**摇定结果 = 可摇集合按权重份额归一的一次抽签；当前可摇集合 = 实例池排除冷却中与触发条件不满足的技能（保底命中时 = 条件满足的全部特殊技）。**连带可判别：把权重当固定百分比、把冷却当只锁高伤技、把蓄力当重击前奏，都是与本规约相悖的旧口径。 +### 精英行：现役敌种的强化版，池＝继承基础池＋附加技 + +精英怪是某个现役敌种的强化版本：玩家看到的是同一种怪（同立绘、名字带「精英·」前缀），数值更强、出招多几样。它在敌人表里是独立的一行——自己的 enemy_id、自己的数值、自己的专属池，和基础敌种的行互不覆盖；外显与内部定义因此可以是一对多（一个外观对应基础行与精英行两份定义）。精英身份由行类承载：敌人表行类新增 elite 值。 + +| 规则 | 含义 | +|---|---| +| 独立行 | 精英＝敌人表行类为 elite 的一行，enemy_id 独立、不与基础敌种同名；名字前缀「精英·」由该行名字行值承载。数值字段（生命、攻击、护甲两轴、数量）与战斗行同一套定义与取值域 | +| 基础敌种引用 | 精英行用基础敌种引用字段指向一个基础敌种的 enemy_id；被指敌种必须在同关战斗行类里存在，指向不存在的敌种或另一条精英行，加载期拒绝 | +| 专属池＝继承＋附加 | 精英行不写自己的池模板，只写附加技清单（{skill_id, weight} 数组）；它的池模板＝基础池＋附加技合并。基础池取自同关、战斗行类、该基础敌种深度带最小的那一行的池模板——继承不复制：基础池调参自动传到精英。附加技的 skill_id 与基础池重复，加载期拒绝 | +| 合并池过同一纪律 | 池构成纪律（恰一普攻、增益 ≤1、妨害 ≤1、至少一行无条件特殊技、悬空引用致命、权重域）校验的对象是合并后的池；开战快照、实例池、冷却、保底、触发条件语义全部不变——精英实例拿到的就是合并后池的快照 | +| 暂不接线 | 精英行落表即合法；开战寻址只按节点类型取战斗或 Boss 行集，精英行在接线前不会被任何节点读到，静置合法、不返回错误。精英遭遇怎么投放到节点，归待办清单「战斗节点遭遇编排方式」条目 | + +举证：**精英池模板 = 基础池条目 ∪ 附加技条目（两者 skill_id 不相交）**；中签率公式不变，可摇权重合计含附加技权重——加附加技会摊薄基础池各技能的中签率，EV 重锚归[难度曲线与Boss](../冒险循环/难度曲线与Boss.md)。各精英行的数值与附加技行值读敌人表（`enemy.tres`），本文不登记。 + ### 触发条件：情境技与闩型解锁共用一套门槛 技能行可以带一个触发条件：条件不满足的拍，这行技能不进可摇集合——与冷却中的排除同一待遇；条件满足时，按正常权重照摇。它服务两类出招：情境技（自身低血才用的防御、上轮玩家停手才会出的偷袭等）让怪物像在"看情况出招"，停手与压血因此有了代价；闩型解锁（半血解锁）让大招只在血量跌破阈值后才可被摇出。两类用例、一套机制——条件只管"现在能不能被摇到"，不改权重、不强制出手。 @@ -236,7 +250,8 @@ Boss 专属身份 = 专属池承载：独占技能 + 权重轮廓（**技能错 | 优先级 | 内容 | 后置原因 | |---|---|---| | P1 | 情境条件触发器（低血触发防御、玩家停手时偷袭技等） | 已实装（三 Boss 闩型＋两示范投放，见「触发条件」节与「首批落地」段） | -| P1 | 个体化变体池（A 型好斗 / B 型守势、精英专属池） | 共识点 A 的 A2 案；登记[待办清单](../../../../待办清单.md) | +| P1 | 个体化变体池（同种个体分型：A 型好斗 / B 型守势） | 共识点 A 的 A2 案；排期 Beta，登记[待办清单](../../../../待办清单.md) | +| P1 | 精英遭遇接线、精英底座光环与描边变色、精英钥石掉落 | 精英行已落表静置（见「精英行」节）；接线归[待办清单](../../../../待办清单.md)「战斗节点遭遇编排方式」条目，视觉二件随怪物设定批，钥石随接线批 | | P1 | 全局特殊间隔旋钮 | 特殊技背靠背实测仍嫌时的备用闸；登记[待办清单](../../../../待办清单.md) | | P1 | 新效应词汇（妨害技 + 必中附加分量已实装——实装面 = L2 Boss 卓尔；多段命中经用户拍板退役） | 妨害类型 + rider_mult 字段已落地；登记[待办清单](../../../../待办清单.md)（已解决移除，去向见状态记录） | | P1 | 敌种扩容与投放节奏（含第二关池与投放） | 投放节奏是关卡命脉，归[难度曲线与Boss](../冒险循环/难度曲线与Boss.md) | @@ -253,7 +268,7 @@ Boss 专属身份 = 专属池承载：独占技能 + 权重轮廓（**技能错 | 参数 | 取值域 | 说明 | |---|---|---| | level_index（关卡序号） | int ≥ 1 | 行集坐标第一维：第几关；每关必有战斗类、深度带 0 的一行（锚行）与至少一行 Boss 类行——加载校验强制；关间台阶的坐标轴，行值投值归[难度曲线与Boss](../冒险循环/难度曲线与Boss.md) | -| row_kind | {battle, boss} | 行类：battle = 战斗节点配池（非 Boss 的战斗节点一律取此类），boss = 终点行集——Boss 战按终点配置，多终点各配一行（走哪条路决定打谁）；开战按节点类型取对应类的行集 | +| row_kind | {battle, boss, elite} | 行类：battle = 战斗节点配池（非 Boss 的战斗节点一律取此类），boss = 终点行集——Boss 战按终点配置，多终点各配一行（走哪条路决定打谁）；elite = 精英行（见核心规则「精英行」节，接线前不被任何节点读到）；开战按节点类型取对应类的行集 | | depth_band | int ≥ 0 | 深度带 = 节点深度所在的区间（定义见核心规则「行集构成纪律」）：配池按带不按点，难度坡随带递增；节点深度落在带与带之间时取首个 ≥ 深度的带键（偏难一侧）；越顶带加载校验判为调参事故；带键投放归[难度曲线与Boss](../冒险循环/难度曲线与Boss.md) | | unit_count | [1, 3] | 遭遇数量区间下界；有上界的行开战时在区间内掷定，教学位节点同样掷骰 | | unit_count_max | [unit_count, 3]，可省略 | 数量区间上界；开战时在区间内掷定本战实际数量；缺省 = 定值 | @@ -263,7 +278,9 @@ Boss 专属身份 = 专属池承载：独占技能 + 权重轮廓（**技能错 | armor_class（护甲等级） | int [0, 999]，缺省 0 | 防守方护甲等级——基础攻击掷点的折扣判定读数，掷点结算归[战斗结算](战斗结算.md)；与 armor_type（克制属性轴）两概念禁止混用；行值投值归[难度曲线与Boss](../冒险循环/难度曲线与Boss.md) | | hp | [1, 999] | 单位生命基线（难度修饰前） | | atk | [0, 999] | 攻击基线 | -| pool（池模板） | {skill_id, weight} 数组，weight ∈ (0, 9999] | 技能行引用在技能表；池构成纪律与悬空引用加载期拒绝（校验在数据配置跨表通道） | +| pool（池模板） | {skill_id, weight} 数组，weight ∈ (0, 9999] | battle / boss 行必填、elite 行禁填；技能行引用在技能表；池构成纪律与悬空引用加载期拒绝（校验在数据配置跨表通道） | +| base_ref（基础敌种引用） | enemy_id 字符串 | 仅 elite 行、必填（其余行类禁填）；须指向同关 battle 行类存在的敌种，悬空或指向 elite 行加载期拒绝 | +| pool_extra（附加技清单） | {skill_id, weight} 数组，weight ∈ (0, 9999]，非空 | 仅 elite 行、必填（其余行类禁填）；skill_id 与基础池不相交；合并后池过池构成纪律 | 技能表（全局单表，技能行主键 skill_id）： @@ -305,6 +322,7 @@ Boss 专属身份 = 专属池承载：独占技能 + 权重轮廓（**技能错 - 表校验：越域值、池权重 ≤ 0、空池、普攻配倍率/冷却、池增益 > 1、skill_id 悬空、行集构成违例（行集内同敌种第二行 / 同带键多行不相邻）均在加载期返回错误并止动；域内合法极端（攻击基线 0）不拒；主角表恰一行、攻击配 0 拒绝。 - 零随机回放：同一动作与受击序列驱动两个独立实例，存活投影、逐实例摇定轨迹、顺位返回序列逐项相同。 - 表实一致：敌人表、主角表、技能表三张配置表的字段与各自字段定义逐字段一致。 +- 精英行：elite 行的池模板 = 基础池（同关、战斗行类、基础敌种深度带最小行）＋附加技清单，开战快照拿到合并后池；基础池改表后精英合并池随之改变；elite 行落表时任何战斗节点与 Boss 节点开战都不读到它；elite 行缺基础敌种引用或附加技清单、基础敌种引用悬空或指向 elite 行、精英 enemy_id 与基础敌种引用同名、附加技与基础池 skill_id 重复、合并池违反池构成纪律、elite 行写自己的池模板、非 elite 行写基础敌种引用或附加技清单——均在加载期返回错误并止动。 ## 待办 diff --git a/design/gdd/systems/表现与支撑/HUD框架.md b/design/gdd/systems/表现与支撑/HUD框架.md index 50deaeb7..00d0f550 100644 --- a/design/gdd/systems/表现与支撑/HUD框架.md +++ b/design/gdd/systems/表现与支撑/HUD框架.md @@ -11,7 +11,7 @@ HUD框架把各玩法系统产生的事实变成玩家看得见、点得动、 ## 系统范围 -边界这样划：本系统管"怎么呈现、怎么翻译输入、弹层怎么排队"。一个动作合不合法、结果算什么意思，归排雷玩法、行动经济、战斗结算等上游裁定；画面具体长什么样、组件落在哪一像素，屏级权威按屏分治——战斗屏是 [battle.md](../../ux/battle.md)、关卡画面是 [level-map.md](../../ux/level-map.md)——本文只锁系统级契约。 +边界这样划：本系统管"怎么呈现、怎么翻译输入、弹层怎么排队"。一个动作合不合法、结果算什么意思，归排雷玩法、行动经济、战斗结算等上游裁定；画面具体长什么样、组件落在哪一像素，屏级权威按屏分治——战斗屏是 [battle.md](../../../ux/battle.md)、关卡画面是 [level-map.md](../../../ux/level-map.md)——本文只锁系统级契约。 负责： @@ -32,7 +32,7 @@ HUD框架把各玩法系统产生的事实变成玩家看得见、点得动、 |---|---| | 任何玩法状态与玩法数值 | 各玩法系统；数值表本体归[数据配置](数据配置.md) | | 合法性判定与机制语义裁定 | [排雷玩法](../排雷循环/排雷玩法.md)、[行动经济](../排雷循环/行动经济.md)、[战斗结算](../战斗循环/战斗结算.md) | -| 屏级布局与动画时长的像素级裁决 | [battle.md](../../ux/battle.md)（战斗屏）与 [level-map.md](../../ux/level-map.md)（关卡画面） | +| 屏级布局与动画时长的像素级裁决 | [battle.md](../../../ux/battle.md)（战斗屏）与 [level-map.md](../../../ux/level-map.md)（关卡画面） | | 美术终稿与动画密度 | [art-bible](../../../art/art-bible.md)与[战斗表现](../战斗循环/战斗表现.md) | | 音频、教学内容、本地化文本生产 | [音频](音频.md)、[教学引导](教学引导.md)、[设置与本地化](设置与本地化.md) | | 任何随机消费 | 无——呈现层零随机 | @@ -61,9 +61,9 @@ HUD框架站在玩家与全部玩法系统之间：挖掘期它是输入的翻 | C 角色信息 | 左下，宽读 `info_panel_w`，高 = 基准屏高 − B 区高 | 生命 / 攻击 / 储备数据框、状态效果槽、小人立绘 | | D 扫雷图 | 中下，宽 = 基准屏宽 − C 区宽 − 列间距，高同 C 区 | 行动点条与按钮组、棋盘本体、toast 槽 | -分区几何的唯一事实源 = `game/data/tables/battle_layout.tres`（经 `ConfigDb.presentation.battle_layout` 读取）；分区尺寸与组件落位的像素级裁决归 [battle.md](../../ux/battle.md)，两份文档只写结构关系、不复写数值。三区结构与双舞台常驻是结构冻结项，修订走文档修订而非调参。节点链进度不在战斗屏呈现——它由关卡画面（选路覆盖层常驻形态）的节点态承载，见[关卡节点地图](../冒险循环/关卡节点地图.md)。 +分区几何的唯一事实源 = `game/data/tables/battle_layout.tres`（经 `ConfigDb.presentation.battle_layout` 读取）；分区尺寸与组件落位的像素级裁决归 [battle.md](../../../ux/battle.md)，两份文档只写结构关系、不复写数值。三区结构与双舞台常驻是结构冻结项，修订走文档修订而非调参。节点链进度不在战斗屏呈现——它由关卡画面（选路覆盖层常驻形态）的节点态承载，见[关卡节点地图](../冒险循环/关卡节点地图.md)。 -**结论**：棋盘格边长由 [battle.md](../../ux/battle.md)「棋盘格尺寸公式」按棋盘区实测面积与板型算出；本文只判"塞不塞得进"，不复制算式与算例。**分辨率档位**：两档=1280×800 基准档（本表全部定值的口径）+1920×1080 档=**全局等比**（stretch canvas_items+aspect keep——16:10 设计在 16:9 窗口为等比 1.35×+左右黑边各 ~96px）；本节与各屏定值一律按 1280 基准档书写，1920 档由引擎等比承载、零重排。 +**结论**：棋盘格边长由 [battle.md](../../../ux/battle.md)「棋盘格尺寸公式」按棋盘区实测面积与板型算出；本文只判"塞不塞得进"，不复制算式与算例。**分辨率档位**：两档=1280×800 基准档（本表全部定值的口径）+1920×1080 档=**全局等比**（stretch canvas_items+aspect keep——16:10 设计在 16:9 窗口为等比 1.35×+左右黑边各 ~96px）；本节与各屏定值一律按 1280 基准档书写，1920 档由引擎等比承载、零重排。 ``` 装板可行性（网格实高 ≤ 棋盘区可用高）： @@ -76,7 +76,7 @@ HUD框架站在玩家与全部玩法系统之间：挖掘期它是输入的翻 | N | 棋盘边长格数 | 读[棋盘生成](../排雷循环/棋盘生成.md)（现行四档；事实源 board_gen.tres） | | 棋盘区宽 / 高 | 扫雷图区基准尺寸 | 由 D 区尺寸扣行动点条高（读 `ap_bar_h`）得出，本表不复制现算值 | -装板可行性由上面的不等式保证；格边长的可读下限见 [battle.md](../../ux/battle.md)，算例由样张渲染脚本按布局表现算、不入文档。棋盘数字直接显示排雷玩法给的真值——呈现层禁止自己算数字，这是"数据层从不说谎"在呈现侧的镜像。 +装板可行性由上面的不等式保证；格边长的可读下限见 [battle.md](../../../ux/battle.md)，算例由样张渲染脚本按布局表现算、不入文档。棋盘数字直接显示排雷玩法给的真值——呈现层禁止自己算数字，这是"数据层从不说谎"在呈现侧的镜像。 ### 提示与弹层：轻提示随起随消、重弹层排队进出 @@ -169,7 +169,7 @@ HUD框架站在玩家与全部玩法系统之间：挖掘期它是输入的翻 ### 营地：可点击场景图 -营地形态**已换代为一张可点击的场景图 + 七物件点选**（现行权威=[camp](../../ux/camp.md)）；全部程序占位视觉（占位纪律延续，2026-10-11 用户令），**视觉与布局终稿归 HUD 营地视觉批**（未立项）。结构现行事实源 = [天赋树](../跨局循环/天赋树.md)「营地=树：统一模型」节。 +营地形态**已换代为一张可点击的场景图 + 七物件点选**（现行权威=[camp](../../../ux/camp.md)）；全部程序占位视觉（占位纪律延续，2026-10-11 用户令），**视觉与布局终稿归 HUD 营地视觉批**（未立项）。结构现行事实源 = [天赋树](../跨局循环/天赋树.md)「营地=树：统一模型」节。 ### 可访问性基线：看得清、不闪、纯鼠标玩得通 @@ -212,7 +212,7 @@ HUD框架站在玩家与全部玩法系统之间：挖掘期它是输入的翻 | [排雷玩法](../排雷循环/排雷玩法.md) | 已开 / 未开格态一眼可辨；悬停预承诺与可挖域常驻指示；移动路径预览即合法性指示；每次拒绝可感知且棋盘面细因可区分；停手被改判可感知 | | [行动经济](../排雷循环/行动经济.md) | 行动点与储备常显；储备清零反馈；棋盘面与资源面拒绝可区分；刷新入口与代价可读 | | [战斗结算](../战斗循环/战斗结算.md) | 未生效类明细行（奖励未生效）的呈现；高光行强调 | -| [关卡节点地图](../冒险循环/关卡节点地图.md) | 节点链进度呈现（关卡画面选路覆盖层节点态承载：暗金已过、金当前、候选下一跳通道亮金、Boss 紫赤描边）；选路覆盖层只读呈现（零自动推进停点语义）——屏级 spec：[level-map](../../ux/level-map.md) | +| [关卡节点地图](../冒险循环/关卡节点地图.md) | 节点链进度呈现（关卡画面选路覆盖层节点态承载：暗金已过、金当前、候选下一跳通道亮金、Boss 紫赤描边）；选路覆盖层只读呈现（零自动推进停点语义）——屏级 spec：[level-map](../../../ux/level-map.md) | | [敌人系统](../战斗循环/敌人系统.md) | 意图线索映射成文且全局恒定；单位顺位与血条可读；敌方共享层数各卡同值 | | [增益状态](../战斗循环/增益状态.md) | 状态栏常显；无状态时整排槽隐藏；有利 / 有害极性呈现不看数值符号 | | [地图战斗资源](../战斗循环/地图战斗资源.md) | 已开格的奖励身份常读；未开格类型微光（英雄周围 8 格内的未开格显示资源类型——概念定义见本篇「未开格类型微光」节） | @@ -236,7 +236,7 @@ HUD框架站在玩家与全部玩法系统之间：挖掘期它是输入的翻 | P1 | 远格点击自动"先移动再挖"复合意图 | 移动免费高频，两击摩擦先经实测验证再裁 | | P1 | Gamepad 焦点序 | 纯鼠标已覆盖 MVP 全部操作 | | P1 | 可访问性正式分层（文本缩放 / 色盲模式 / 按键重映射） | 归[设置与本地化](设置与本地化.md)设置项全集裁决（2026-09-27 拍板不另立专项文档） | -| P1 | 相邻域屏（节点奖励 / 关卡结算）完整屏形态 | 归后续 UX 文档（关卡结算屏 spec 已建 [level-clear](../../ux/level-clear.md)；节点奖励屏 spec 已在役：[node-reward](../../ux/node-reward.md) v2.5 令牌池口径）；MVP 以覆盖层反馈承载 | +| P1 | 相邻域屏（节点奖励 / 关卡结算）完整屏形态 | 归后续 UX 文档（关卡结算屏 spec 已建 [level-clear](../../../ux/level-clear.md)；节点奖励屏 spec 已在役：[node-reward](../../../ux/node-reward.md) v2.5 令牌池口径）；MVP 以覆盖层反馈承载 | | P2 | 提示一次性作用域升级为存档级"一生一次" | 归[存档序列化](存档序列化.md)与[元进度](../跨局循环/元进度.md)后重议 | | P2 | 调试面板退役 | 正式侧归元进度；诊断按钮保留为调试设施 | | P2 | 探测类秘宝的显影呈现面 | 接口归[秘宝](../跨局循环/秘宝.md)定稿批 | diff --git a/design/gdd/systems/表现与支撑/数据配置.md b/design/gdd/systems/表现与支撑/数据配置.md index e389308b..547fba9a 100644 --- a/design/gdd/systems/表现与支撑/数据配置.md +++ b/design/gdd/systems/表现与支撑/数据配置.md @@ -70,7 +70,7 @@ | 关卡表 | 逐关节点图与层名 | [冒险结构](../冒险循环/冒险结构.md) | | 冒险表 | 关卡大奖励与钥石入账（单行全局） | [冒险结构](../冒险循环/冒险结构.md) | | 元进度表 | 元进度字段（现行五行族：属性锻造 / Boss 钥石 / 工坊阈值 / 换算率 / 同调刷新升级行族） | [元进度](../跨局循环/元进度.md) | -| 战斗屏布局表（`battle_layout.tres`） | 分区几何、B 区连续地面层高与明细带两态高（单行；呈现层布局配置，非玩法数值——供呈现层与样张工具同源读取） | [战斗屏规格](../../ux/battle.md)（结构）／[HUD框架](HUD框架.md)（呈现常量） | +| 战斗屏布局表（`battle_layout.tres`） | 分区几何、B 区连续地面层高与明细带两态高（单行；呈现层布局配置，非玩法数值——供呈现层与样张工具同源读取） | [战斗屏规格](../../../ux/battle.md)（结构）／[HUD框架](HUD框架.md)（呈现常量） | 举证：本节为数据纪律约定，无计算。违规检测 = 静态扫描加人工复核，随各表回填定稿与里程碑检查执行。 @@ -174,7 +174,7 @@ | 优先级 | 内容 | 后置原因 | |---|---|---| -| P1 | 战斗级可回放集成测试（同主种子同动作序列，步骤流逐行相同） | 需战斗域载体，随[战斗结算](../战斗循环/战斗结算.md)回放验收兑现 | +| P1 | 战斗级可回放闭环测试（同主种子同动作序列，步骤流逐行相同） | 需战斗域载体，随[战斗结算](../战斗循环/战斗结算.md)回放验收兑现 | | P1 | 难度曲线导出工具（无窗口导出行解析矩阵供比对） | 难度审计的离线载体，[难度曲线与Boss](../冒险循环/难度曲线与Boss.md)期交付物 | | P2 | 正式包构建的致命表现验证与调试覆盖结构性不存在验证 | 挂首次正式导出检查清单 | | P2 | 进度键表的调试覆盖行寻址语法 | 调试覆盖现只支持单行全局表字段，行寻址登记为后续扩展 | diff --git a/design/gdd/systems/表现与支撑/设置与本地化.md b/design/gdd/systems/表现与支撑/设置与本地化.md index f066939d..3995e453 100644 --- a/design/gdd/systems/表现与支撑/设置与本地化.md +++ b/design/gdd/systems/表现与支撑/设置与本地化.md @@ -28,7 +28,7 @@ | 不负责 | 归谁 | |---|---| | 呈现语义与可访问性基线本体（字号下限、闪烁上限、纯鼠标可玩等） | [HUD 框架](HUD框架.md) | -| 逐行结算的呈现规则 | [battle.md](../../ux/battle.md) 与 [HUD 框架](HUD框架.md)，本文只引用 | +| 逐行结算的呈现规则 | [battle.md](../../../ux/battle.md) 与 [HUD 框架](HUD框架.md)，本文只引用 | | 减动效开启后动画怎么演 | [战斗表现](../战斗循环/战斗表现.md)——本文提供开关，动画侧兑现归对方 | | 音量调节对声音怎么生效 | [音频](音频.md)——生效侧归对方，口径已对齐 | | 文案内容本体（教学条目、界面用语等写了什么） | 各系统文档——本文只做翻译生产，不改含义 | @@ -60,7 +60,7 @@ | 输入 | 登记处 | 将来要做的 | |---|---|---| -| 减动效开关 | [HUD 框架](HUD框架.md)的可访问性基线与 [battle.md](../../ux/battle.md)的呈现承诺；[战斗表现](../战斗循环/战斗表现.md)已登记承接其动画侧 | 提供开关：开启后全部动画有时长减半或直达终态的通路。呈现侧的约束以 battle.md 与 HUD 框架为权威，本文不复述 | +| 减动效开关 | [HUD 框架](HUD框架.md)的可访问性基线与 [battle.md](../../../ux/battle.md)的呈现承诺；[战斗表现](../战斗循环/战斗表现.md)已登记承接其动画侧 | 提供开关：开启后全部动画有时长减半或直达终态的通路。呈现侧的约束以 battle.md 与 HUD 框架为权威，本文不复述 | | 音量控制入口 | 归档对本系统的常规分工登记；[音频](音频.md)已登记同款分工 | 在设置里提供音量入口；生效侧归音频（口径已对齐） | | 键位映射表 | [HUD 框架](HUD框架.md)定稿登记的交付物输入（全键族） | 如何转化成设置项（比如是否允许改键）待设计 | | 结算风味词 | 归档概念层增补批随巢穴隐喻换轴登记（"封印 / 镇 / 反制"一类类型风味词），只登记了存在、各归各的时机 | 内容与形态未定，本文只登记这条输入在 | diff --git a/design/gdd/systems/跨局循环/元进度.md b/design/gdd/systems/跨局循环/元进度.md index c01abf51..b117b56a 100644 --- a/design/gdd/systems/跨局循环/元进度.md +++ b/design/gdd/systems/跨局循环/元进度.md @@ -103,7 +103,7 @@ ### 解锁界面：双入口框架 -（2026-09-18 拍板；入口拓扑=三入口化）营地消费面（消费钥石、查看与管理永久强化）经主菜单「进入存档」→选档界面→进档/新档进入，主菜单不再设营地独立钮；局内状态面板（游戏非实时无暂停语义）也可查看钥石余额与本局冒险信息（只读）。钥石余额在 HUD 常驻展示。呈现 spec：[ux/camp.md](../../ux/camp.md) v1.0（退役/封存件「已退役/已解锁·能力封存中」呈现语义随 spec 落位）；视觉终稿已落码。本节锁框架与需求，呈现细节归 spec；局内状态面板入口已实装（实机目检待用户，待办清单登记条在册）。 +（2026-09-18 拍板；入口拓扑=三入口化）营地消费面（消费钥石、查看与管理永久强化）经主菜单「进入存档」→选档界面→进档/新档进入，主菜单不再设营地独立钮；局内状态面板（游戏非实时无暂停语义）也可查看钥石余额与本局冒险信息（只读）。钥石余额在 HUD 常驻展示。呈现 spec：[ux/camp.md](../../../ux/camp.md) v1.0（退役/封存件「已退役/已解锁·能力封存中」呈现语义随 spec 落位）；视觉终稿已落码。本节锁框架与需求，呈现细节归 spec；局内状态面板入口已实装（实机目检待用户，待办清单登记条在册）。 ### 单局循环零依赖：排期边界的推论 diff --git a/design/gdd/systems/跨局循环/生涯.md b/design/gdd/systems/跨局循环/生涯.md index a36c7bea..ba603588 100644 --- a/design/gdd/systems/跨局循环/生涯.md +++ b/design/gdd/systems/跨局循环/生涯.md @@ -69,9 +69,9 @@ | 界面 | 管什么（现状指证） | 与生涯的边界 | |---|---|---| -| 营地（[camp UX spec](../../ux/camp.md)） | 跨局成长**操作**面（花钥石买强化 / 装配 / 点树——营地场景图＋五功能窗口形态）；原底栏「最近冒险」条带已撤下（P6 甲），逐局历史回看唯一归生涯 | 营地不改生涯只读定位；生涯不做任何购买入口，也不放「去买」按钮。营地条带已撤（P6 甲） | +| 营地（[camp UX spec](../../../ux/camp.md)） | 跨局成长**操作**面（花钥石买强化 / 装配 / 点树——营地场景图＋五功能窗口形态）；原底栏「最近冒险」条带已撤下（P6 甲），逐局历史回看唯一归生涯 | 营地不改生涯只读定位；生涯不做任何购买入口，也不放「去买」按钮。营地条带已撤（P6 甲） | | 状态面板 | **局内**只读查看这一局进行中的钥石与本局冒险进度 | 状态面板看当局当前值，生涯看跨局累计与历史；局内无生涯入口（P4 甲） | -| 结算屏（[settlement-summary UX spec](../../ux/settlement-summary.md)） | 冒险收束当下的入账明细——冒险收束时由结算屏呈现入账明细与钥石明细（复用终局面账行的呈现形态） | 收束当下的呈现保留不动；生涯承接的是收束之后的任意时刻回看 | +| 结算屏（[settlement-summary UX spec](../../../ux/settlement-summary.md)） | 冒险收束当下的入账明细——冒险收束时由结算屏呈现入账明细与钥石明细（复用终局面账行的呈现形态） | 收束当下的呈现保留不动；生涯承接的是收束之后的任意时刻回看 | | 帮助手册（Beta 批，未实装——教学内容归 Beta 帮助手册） | 讲「怎么玩」 | 生涯讲「我玩过什么」。图鉴条目文案与手册是否共用内容源，接口登记归 Beta 批一并裁 | | 图例面板 | 局内符号/徽标即时解码 | 不合并——图例是局内解码面，图鉴是跨局收集面 | diff --git a/design/gdd/术语表.md b/design/gdd/术语表.md index ffd8907d..e58d186f 100644 --- a/design/gdd/术语表.md +++ b/design/gdd/术语表.md @@ -111,7 +111,7 @@ | 图类型 | 棋盘生成产物 `board_type` 的中文名——三关换皮的单位（同款地砖换色板） | | 方向稿 | 冻结前的方向性候选稿，供气质目检；过目检后才进机检冻结 | | 站桩 | 战斗画面区（B 区）里角色直立立绘的显示形态（配血条与状态行） | -| 显示档 | 站桩立绘的显示尺寸规则——源用原稿分辨率入包（禁降采样），显示按三档绝对高（小型 96／中型 144／大型 188）缩放、宽随源比例；定值单点见[美术圣经](../art/art-bible.md) §8.2 站桩立绘显示档条 | +| 显示档 | 站桩立绘的显示尺寸规则——源用原稿分辨率入包（禁降采样），显示按三档绝对高缩放、宽随源比例；定值单点见[美术圣经](../art/art-bible.md) §8.2 站桩立绘显示档条（档值定值面＝站桩呈现守门测试） | | 徽章 | 库存条与结算明细用的小图标（与格面类型微光预读相区分） | ## 开发流程 @@ -179,6 +179,7 @@ | 罕见（档位名） | 稀有（2026-10-26 用户裁入表：旧三档档位名，现行四级第三档=稀有；散文形容词义不受限） | | 通关 | 关卡完成（单关）／冒险成功（整局）——2026-10-26 用户裁：主体明确短语族替代歧义单义词 | | 冒险终结 | 冒险落幕——2026-10-26 通关口径统一批 | +| 集成测试 / 集成用例 / 集成层 / 集成侧 / 集成宿主 / 集成族 | 单元测试（2026-11-07 用户裁层级合并——跨系统真实路径闭环套件归单元层，三套件实体迁移 tests/unit/；测试层识别靠三元组〔职责×触发时间点×覆盖面积，权威表=test-conventions「测试层三元组」节〕，层级名只是代称；闭环套件的性质归属由各套件头注承载） | ## 对外命名纪律（玩家可见命名，2026-10-11 用户令） diff --git a/design/gdd/ux/battle.md b/design/ux/battle.md similarity index 97% rename from design/gdd/ux/battle.md rename to design/ux/battle.md index a994d50d..246251ef 100644 --- a/design/gdd/ux/battle.md +++ b/design/ux/battle.md @@ -142,7 +142,7 @@ - N ＝ 棋盘长宽两边的较大者；格间距 2px；垂直预留 24px（上 12 / 下 12）；悬崖厚度 8px；结构钳制区间 [26, 46]px。 - 格边长可读性以用户验收的现行画面为锚点（2026-11-01 用户裁——现行渲染值即基准，基座档 14×14＝28px 达标）；全域不设人造的格边长可读阈值。结构钳制 [26, 46] 只管算式结果不越界；格边长接线守卫＝生产写入值与上式单点算式的返回值严格相等，最大板型的推定读数仅留痕观察、不作判红依据。 -- N 的取值与每关板型的对应关系读[棋盘生成](../systems/排雷循环/棋盘生成.md)，现行值的事实源是 `data/tables/board_gen.tres`。 +- N 的取值与每关板型的对应关系读[棋盘生成](../gdd/systems/排雷循环/棋盘生成.md)，现行值的事实源是 `data/tables/board_gen.tres`。 - 数字字号 = max(18, ceil(格边长 × 0.5))，像素字体整数倍缩放（canvas_items stretch 保证清晰）。 算例不入文档：棋盘区可用面积随布局表与板型变化，不是契约值——现算并绘在整屏样张上，本文件不复写。 @@ -154,7 +154,7 @@ | B | 主角站桩立绘 | 站桩（无框立绘+落影） | HP 条落底盘（2026-10-06 方案二拍板：站桩排式 = **立绘→血条→状态**，全场血条对齐一线；血条嵌石板位、台缘线留作地面线；不悬浮头顶——高盒下血条-立绘空洞，用户点名否决）、状态效果小图标一排挂血条正下方（形状+色相双通道、层数角标；空态不占位退化为空行）——**HP 与状态效果的唯一展示面（2026-09-26 信息归属拍板；悬停 tooltip〔来源+语义+剩余结算次数〕职责在本组件）**；攻击值等规划数据仍归 C 区数据框（2026-09-20 全站桩拍板，英雄卡退役） | 悬停状态小图标看 tooltip | HUD 视图拆分改造 | | B | 敌人站桩立绘 ×1–3 | 站桩（无框立绘+落影） | 血条+顺位徽标落底盘（同主角排式，2026-10-06 方案二；**大体档〔显示 >150px 级：drider/duergar_king〕允许向上溢出盒顶 N px（N 由实装实算，溢出判定与背景无关），血条仍落底**）、状态小图标挂血条正下方（敌方增益按个体呈现——各立绘只显示它自己名下的状态实例〔蓄力/硬化/削弱/暴走/警觉，2026-11-02 个体化裁〕；数据源 = 战斗结算流水经增益状态投影，敌人系统×4④；无行为环点〔proposal §2.4〕，意图占位 = 本拍摇定结果的动画占位——普通攻击零表示 / 特殊技类型级提示，**意图徽标悬浮头顶上方，探顶档压胸**，敌方增益〔蓄力/硬化〕入状态图标行）；死亡灰化加碎裂退场直接演在立绘上（2026-09-20 全站桩拍板，敌人卡退役）；血条下名字行 = 纯名字 + 护甲类型图标（形状+色相双通道，与状态图标同行共存，状态空时为纯名字），AC 数值不展示——2026-09-26 终裁（用户口径：HP 信息已足够，攻防数值不直接写上；护甲类型图标保留克制对策可读性——类型可读、数值隐藏） | 只读 | 新建 | | B | 轮次·阶段指示 | 标签 | "第 N 轮 · 挖掘中/结算中"（终局定格「战斗结束」；Boss 变体附 Boss 名） | 只读 | 新建 | -| B | 结算明细带 | 滚动列表 | 结算期逐行流水（[战斗结算](../systems/战斗循环/战斗结算.md#明细流水每一行都能指回你刚才的哪一步棋) 9 类行协议）；挖掘期收起为上轮摘要 1 行 | 无明细回看——带保留单行摘要，冒险中回看归「生涯」 | 改造 | +| B | 结算明细带 | 滚动列表 | 结算期逐行流水（[战斗结算](../gdd/systems/战斗循环/战斗结算.md#明细流水每一行都能指回你刚才的哪一步棋) 9 类行协议）；挖掘期收起为上轮摘要 1 行 | 无明细回看——带保留单行摘要，冒险中回看归「生涯」 | 改造 | | B | 结算明细回看（已退役） | —— | 冒险中回看归「生涯」；回看覆盖层为未接线遗留件（待办清单登记） | —— | 未接线 | | C | 攻击数据框 | 直角细线数据框 | 攻击值 + 修正来源角标 + 护甲 AC（AC 二轮拍板 2026-09-26 补入——我方 AC 唯一展示面；HP 与状态归 B 区站桩、RAP 归 D 区 AP 条，不在本组件） | 只读 | HUD 视图拆分 | | C | 秘宝槽 | 图标槽 ×4 | 四槽壳在役、空槽占位（标题「秘宝」，悬停「秘宝槽（空）」）；局内两步使用与关卡域库存随秘宝过渡形态退役——现行秘宝 = 营地同调装配件（秘宝.md），本区展示重接归装配面 | 悬停 tooltip | 已实装 | @@ -282,7 +282,7 @@ | 弃图刷新（挖掘期，非轮出口） · 刷新尝试遥测 | 刷新使用（难度曲线与Boss OQ6）与行动经济 OQ3 预警阈值观测；每轮 0–2 次（布局决策 4 cap=2） | {受理结果: 受理 / 拒因 RAP 不足 / 拒因触上限, 本轮第几次刷新: 1..2} | | 拒绝/voided · 拒绝遥测 | 拒绝来源（板面/资源/相位三源）与细分原因 | {拒绝来源: 板面/资源/相位, 细分原因} | | 提示触发/关闭 · 提示展示遥测 | 提示类型 | {提示类型: chord 提示 / 无相邻可挖格} | -| 呈现订阅（不改核心） | 排雷玩法三事件 / [战斗结算](../systems/战斗循环/战斗结算.md#明细流水每一行都能指回你刚才的哪一步棋)步骤流（9 类行协议，含终局判定行） / 战斗结束 / 关卡完成 | 载荷 schema 成文义务见 §Data Requirements（HUD框架硬性要求） | +| 呈现订阅（不改核心） | 排雷玩法三事件 / [战斗结算](../gdd/systems/战斗循环/战斗结算.md#明细流水每一行都能指回你刚才的哪一步棋)步骤流（9 类行协议，含终局判定行） / 战斗结束 / 关卡完成 | 载荷 schema 成文义务见 §Data Requirements（HUD框架硬性要求） | **持久状态写入**全部经组合根唯一路径（意图批次提交 / 刷新意图提交 / 关卡推进）——UI 层禁直调核心写（架构七原则"依赖单向组合根"）。 @@ -313,7 +313,7 @@ | BFS 移动路径 | 排雷玩法 路径规划只读面 | Read | 布局决策 3 合法性指示消费 | | 拒绝原因 | 排雷玩法 细分原因封闭枚举 + 行动经济 资源面 | Read | 三源（板面/资源/相位）映射文案——呈现层契约成文；资源面原因无上游载荷（行动经济仅回受理与否，细分原因仅调试诊断可见），客户端按动作上下文推断 | | AP / RAP / 本轮刷新计数 | 行动经济 | Read | 常显；刷新入口可用性 = RAP 读数客户端预判（RAP≥8）+ 刷新意图提交的受理回执（行动经济 无刷新可用性预查询——仅受理与否的回执 + 只读观测量；行动经济 EC13 拒绝合法可见） | -| 结算流水行（9 类封闭协议） | [战斗结算](../systems/战斗循环/战斗结算.md#明细流水每一行都能指回你刚才的哪一步棋) 流水协议 | Read | 逐行来源标注（P2）；未生效类行（奖励未生效）聚合计数呈现 | +| 结算流水行（9 类封闭协议） | [战斗结算](../gdd/systems/战斗循环/战斗结算.md#明细流水每一行都能指回你刚才的哪一步棋) 流水协议 | Read | 逐行来源标注（P2）；未生效类行（奖励未生效）聚合计数呈现 | | 判定胜负 | 战斗结算 判定段 | Read | 终局画面数据锚 | | 敌单位 生命/顺位/摇定动作（技能标识·类型·名称）/敌方增益/敌单位标识/存活 | 敌人系统 只读面（经战斗结算呈现快照） | Read | 意图线索映射全局恒定（敌人系统×4②，技能池批三档口径）；**销毁前捕获**（缺陷②教训） | | 状态效果投影（含空态/极性/溢出） | 增益状态 投影口径 | Read | 极性映射数据源 = 战斗结算效果表语义，非幅度符号（增益状态×③） | @@ -332,7 +332,7 @@ ## Accessibility -无障碍基线权威 = [HUD框架](../systems/表现与支撑/HUD框架.md)「可访问性基线」节；不再另立专项文档（2026-09-27 拍板，见 OQ2）。本 spec 内建基线承诺（呈现侧落地）： +无障碍基线权威 = [HUD框架](../gdd/systems/表现与支撑/HUD框架.md)「可访问性基线」节；不再另立专项文档（2026-09-27 拍板，见 OQ2）。本 spec 内建基线承诺（呈现侧落地）： - **对比**：全部格底/面板底对数字墨 ≥4.5:1（WCAG AA）——art-bible §4.1 硬指标已可测（#33261B/#C9AF83 = 6.9:1 实测）；UI 数据一律墨族素面 - **色弱冗余**：无任何信息仅靠色相承载——格态靠完整/碎裂形；奖励金 vs 危险红靠剪影+运动；UI 红/金强调对加图标+文案冗余；Boss 靠形状独占（art-bible §4.5 清单逐项成立） @@ -397,8 +397,8 @@ ## Open Questions -1. **Player journey map——已完成（2026-09-27 拍板：不建）**：实现前补建的前提随战斗屏实装失效；情绪曲线事实源 = art-bible §2 能量档，真人体验观测与结论回流 = [体验验证清单](../../../体验验证清单.md) -2. **无障碍专项文档——已完成（2026-09-27 拍板：不另立 design/accessibility-requirements.md）**：基线（对比/色弱/字号/闪烁/减动效/纯鼠标/中文字体）权威 = [HUD框架](../systems/表现与支撑/HUD框架.md)「可访问性基线」节；正式分层（文本缩放/色盲模式/按键重映射）归 [设置与本地化](../systems/表现与支撑/设置与本地化.md) 待设计问题清单 #1（设置项全集裁决时定）；本 spec §Accessibility 为呈现侧落地承诺 +1. **Player journey map——已完成（2026-09-27 拍板：不建）**：实现前补建的前提随战斗屏实装失效；情绪曲线事实源 = art-bible §2 能量档，真人体验观测与结论回流 = [体验验证清单](../../体验验证清单.md) +2. **无障碍专项文档——已完成（2026-09-27 拍板：不另立 design/accessibility-requirements.md）**：基线（对比/色弱/字号/闪烁/减动效/纯鼠标/中文字体）权威 = [HUD框架](../gdd/systems/表现与支撑/HUD框架.md)「可访问性基线」节；正式分层（文本缩放/色盲模式/按键重映射）归 [设置与本地化](../gdd/systems/表现与支撑/设置与本地化.md) 待设计问题清单 #1（设置项全集裁决时定）；本 spec §Accessibility 为呈现侧落地承诺 3. **interaction-patterns.md——已建成**：本 spec 引入的四 pattern（双源拒绝反馈/逐行兑现明细带/悬停预承诺光标/点阵资源显示）均已入库成文（pattern 1/3/4/5） 4. **战斗表现美术测试**（game-concept 已登记，战斗表现前强制）：本 spec 的常驻双舞台分屏（布局决策 1）是测试的布局输入——**敌人卡形态已裁决（2026-09-20 用户看对照样张拍板）：全站桩式（无框立绘+底座），主角同样站桩、状态小图标挂血条下，卡片式整体退役**；站桩式不改变分区结构。对照样张已存档（敌人卡与站桩式对照样张） 5. **移动动画形态**（布局决策 3）：≤150ms 短滑为推荐值，playtest 观测「移动太瞬/太拖」反馈后调 diff --git a/design/gdd/ux/camp.md b/design/ux/camp.md similarity index 80% rename from design/gdd/ux/camp.md rename to design/ux/camp.md index 6db4ea18..f9aaf9c5 100644 --- a/design/gdd/ux/camp.md +++ b/design/ux/camp.md @@ -1,8 +1,8 @@ # 营地场景 UX spec（camp） > 状态：v2.8（现行） -> 事实源：本 spec（呈现）＋ [元进度](../systems/跨局循环/元进度.md)（机制） -> 美术画法：[art-bible](../../art/art-bible.md) §6.2／§7.5；素材命名与路径：[asset-path-map](../../art/asset-path-map.md) +> 事实源：本 spec（呈现）＋ [元进度](../gdd/systems/跨局循环/元进度.md)（机制） +> 美术画法：[art-bible](../art/art-bible.md) §6.2／§7.5；素材命名与路径：[asset-path-map](../art/asset-path-map.md) > 相邻：[level-map.md](level-map.md)（主菜单语境） ## 定位 @@ -26,9 +26,9 @@ **场景按要素分层（10 张）**：远景天空／远山／整片地面／门洞内的小路合成 `scene_camp_bg` 背景层（z0，不透明全幅）；中景木围墙独立成 `scene_camp_wall` 围墙层（z1，透明底，门洞处留透明缺口）；其余八个物件层各一张、由上往下叠。门洞是围墙层的透明缺口，透出背景层画的**一条通向远处的小路**，不可填死。 -**地平线在终稿 y367**（自画面底部往上约 46%），其上是天空与远山、其下整片地面；**中景围墙带 y203–367**，桩身 150、门柱 164；近景物件允许压住围墙（围墙不可点，z 序在近景物件之下），**唯一例外＝中间门洞必须留空、不被任何物件遮挡**。围墙形态、门扇比例与帐篷尺寸的现行口径归 [art-bible](../../art/art-bible.md) §6.2，本 spec 不再复述。 +**地平线在终稿 y367**（自画面底部往上约 46%），其上是天空与远山、其下整片地面；**中景围墙带 y203–367**，桩身 150、门柱 164；近景物件允许压住围墙（围墙不可点，z 序在近景物件之下），**唯一例外＝中间门洞必须留空、不被任何物件遮挡**。围墙形态、门扇比例与帐篷尺寸的现行口径归 [art-bible](../art/art-bible.md) §6.2，本 spec 不再复述。 -坐标草案与分层验收判据见 [camp-scene-prompts](../../art/camp-scene-prompts.md) §2.3／§4（10 张口径现行事实源）；2026-10-22 美术方案讨论沿革查 git 提交史。 +坐标草案与分层验收判据见 [camp-scene-prompts](../art/camp-scene-prompts.md) §2.3／§4（10 张口径现行事实源）；2026-10-22 美术方案讨论沿革查 git 提交史。 ## 点选反馈（根态） @@ -38,7 +38,7 @@ ## 顶栏 -钥石余额常驻画面顶部一行小 HUD 栏：高 48px、全宽窄条、**浮层覆盖在场景图上层，不挤压画面**。栏体底＝营地头带深棕 `#6E4526`（token `CAMP_HEADER_BAND`，色值出处 [art-bible](../../art/art-bible.md) §7.2 五 token 对齐表）× **不透明度 0.80**——半透明系定值，底下画面透出 20%。栏内**只放钥石徽章一件**，右位、顶格落座（徽章自高 48px＝栏高，无顶距可言），左位不放件。验收：目检〈顶栏成一条可辨窄带、徽章落在带内〉＋机检〈栏体呈色对其下方落位带底色对比 ≥3:1〉。刷新入口已实装＝营地刷新单口（进档与营地内写口尾触发，现开界面与顶栏余额同步取现值）。 +钥石余额常驻画面顶部一行小 HUD 栏：高 48px、全宽窄条、**浮层覆盖在场景图上层，不挤压画面**。栏体底＝营地头带深棕 `#6E4526`（token `CAMP_HEADER_BAND`，色值出处 [art-bible](../art/art-bible.md) §7.2 五 token 对齐表）× **不透明度 0.80**——半透明系定值，底下画面透出 20%。栏内**只放钥石徽章一件**，右位、顶格落座（徽章自高 48px＝栏高，无顶距可言），左位不放件。验收：目检〈顶栏成一条可辨窄带、徽章落在带内〉＋机检〈栏体呈色对其下方落位带底色对比 ≥3:1〉。刷新入口已实装＝营地刷新单口（进档与营地内写口尾触发，现开界面与顶栏余额同步取现值）。 ## 叠层与开合 diff --git a/design/gdd/ux/interaction-patterns.md b/design/ux/interaction-patterns.md similarity index 96% rename from design/gdd/ux/interaction-patterns.md rename to design/ux/interaction-patterns.md index df9516fc..67b9818b 100644 --- a/design/gdd/ux/interaction-patterns.md +++ b/design/ux/interaction-patterns.md @@ -4,7 +4,7 @@ > **Author**: user + ux-designer > **Last Updated**: 2026-10-29 > **Template**: Interaction Pattern Library -> **来源**: `design/gdd/ux/battle.md` 已拍板内容的成文固化——本库不引入新设计决策 +> **来源**: `design/ux/battle.md` 已拍板内容的成文固化——本库不引入新设计决策 --- @@ -84,7 +84,7 @@ MVP 未使用标准控件（不入库）：toggle / dropdown / input field / tab **Description**: 轮末结算逐行流水实时呈现——「扫雷之因逐行兑现为战果」（P2 归因）的承载面。挖掘期收起为 1 行上轮摘要；结算期展开为实时流（带高读 `log_band_h_settle`）。 **Specification**: -- 数据源：[战斗结算](../systems/战斗循环/战斗结算.md#明细流水每一行都能指回你刚才的哪一步棋)步骤流（9 类行封闭协议（现行）；公共字段：来源类别 / 来源格 / 轮次 / 显示名 / 数值 / 可空高光标记）；**无来源行 = 断言失败** +- 数据源：[战斗结算](../gdd/systems/战斗循环/战斗结算.md#明细流水每一行都能指回你刚才的哪一步棋)步骤流（9 类行封闭协议（现行）；公共字段：来源类别 / 来源格 / 轮次 / 显示名 / 数值 / 可空高光标记）；**无来源行 = 断言失败** - 行模板：「{行为} {值} → {目标}（来源）」——来源标注（第 N 轮 · 安全格式）；行文案最长 token = 来源标签（4 汉字封闭枚举），模板预留 40% 膨胀宽度 - 聚合纪律：未生效类行（奖励未生效——现行 9 类行协议唯一未生效型）按聚合计数呈现（防逐行惩罚轰炸）；衰减行聚合计数；效果行数值 = 单次贡献值、禁与池合成值相加呈现；零值行可见不吞（免伤轮归因不断点） - 高亮：高亮标记（封印标中、清图奖励、完美破除） → 金框强调；完美封印 = 独立高光行 + 全屏喝彩级反馈。「完美破除」的判据句读作「本板首次标错受检」，不等于完美资格已失——专长「完美保险」可在本场首次标错时豁免，实际资格按有效误标（误标总数 − 豁免数）判定 @@ -92,7 +92,7 @@ MVP 未使用标准控件（不入库）：toggle / dropdown / input field / tab - 击杀标记呈现（H3 数据源 = 战斗结算流水击杀结果字段） **When to Use**: 任何「因果可归因」的逐行流水呈现 -**When NOT to Use**: 自造行类型/字段（9 类封闭枚举（现行）——增删 = 接口漂移，须走[《战斗结算》](../systems/战斗循环/战斗结算.md#明细流水每一行都能指回你刚才的哪一步棋)修订） +**When NOT to Use**: 自造行类型/字段（9 类封闭枚举（现行）——增删 = 接口漂移，须走[《战斗结算》](../gdd/systems/战斗循环/战斗结算.md#明细流水每一行都能指回你刚才的哪一步棋)修订） **Reference**: battle.md §Component Inventory 结算明细带、§AC 信息与归因；归档《战斗结算》（b1-settlement.md）Core Rule 14 / Visual Req diff --git a/design/gdd/ux/level-clear.md b/design/ux/level-clear.md similarity index 94% rename from design/gdd/ux/level-clear.md rename to design/ux/level-clear.md index 3b865b1b..48c9c710 100644 --- a/design/gdd/ux/level-clear.md +++ b/design/ux/level-clear.md @@ -22,7 +22,7 @@ ## 现行载体与目标形态（重要边界） -本屏**没有独立新屏**：现行与 MVP 目标载体都是关卡收束时刻的覆盖层反馈（[HUD框架](../systems/表现与支撑/HUD框架.md) P1 行「相邻域屏完整屏形态：MVP 以覆盖层反馈承载」）。本 spec 锁义务与数据锚，不锁视觉形态；完整屏形态待 P1 屏实装时定。 +本屏**没有独立新屏**：现行与 MVP 目标载体都是关卡收束时刻的覆盖层反馈（[HUD框架](../gdd/systems/表现与支撑/HUD框架.md) P1 行「相邻域屏完整屏形态：MVP 以覆盖层反馈承载」）。本 spec 锁义务与数据锚，不锁视觉形态；完整屏形态待 P1 屏实装时定。 | 时刻 | 载体（目标形态） | 呈现内容 | |---|---|---| @@ -93,7 +93,7 @@ ## Accessibility -沿用 [HUD框架](../systems/表现与支撑/HUD框架.md)「可访问性基线」节全量（对比/色弱/字号/闪烁/减动效/纯鼠标/中文字体）——本屏无新增承诺。结算数字是本屏信息主载体，遵守同一字号下限与对比硬指标。 +沿用 [HUD框架](../gdd/systems/表现与支撑/HUD框架.md)「可访问性基线」节全量（对比/色弱/字号/闪烁/减动效/纯鼠标/中文字体）——本屏无新增承诺。结算数字是本屏信息主载体，遵守同一字号下限与对比硬指标。 ## Acceptance Criteria diff --git a/design/gdd/ux/level-map.md b/design/ux/level-map.md similarity index 94% rename from design/gdd/ux/level-map.md rename to design/ux/level-map.md index 04dcfd14..22652e73 100644 --- a/design/gdd/ux/level-map.md +++ b/design/ux/level-map.md @@ -7,7 +7,7 @@ > **Template**: UX Spec > **覆盖范围**: 独立屏形态（关卡停点全景）· 入口停点 · 岔路停点 · 单链停点 · 放弃冒险入口 > **不覆盖**: 节点覆盖层（NodeOverlay——奖励/恢复兑付反馈，spec：[node-reward.md](node-reward.md)）、商店覆盖层（spec：[shop.md](shop.md)）、关卡结算屏（[level-clear.md](level-clear.md)）、战斗屏（[battle.md](battle.md)） -> **机制权威**: [关卡节点地图](../systems/冒险循环/关卡节点地图.md)（选路、兑付、停点语义）；图的来源 = [关卡节点图生成](../systems/冒险循环/关卡节点图生成.md)（参数化长图——只换图的来源与形态，不换本屏的呈现语义；多终点时各终点均带 Boss 标记，标记语义不变、数量随图；图形态随参数变化，布局自适应，形态不进呈现代码）；**系统契约**: [HUD框架](../systems/表现与支撑/HUD框架.md)（订阅纪律、模态层级、可访问性基线） +> **机制权威**: [关卡节点地图](../gdd/systems/冒险循环/关卡节点地图.md)（选路、兑付、停点语义）；图的来源 = [关卡节点图生成](../gdd/systems/冒险循环/关卡节点图生成.md)（参数化长图——只换图的来源与形态，不换本屏的呈现语义；多终点时各终点均带 Boss 标记，标记语义不变、数量随图；图形态随参数变化，布局自适应，形态不进呈现代码）；**系统契约**: [HUD框架](../gdd/systems/表现与支撑/HUD框架.md)（订阅纪律、模态层级、可访问性基线） > **生成图随动登记**：入口停点候选数＝入口个数（1 或多，多入口并列呈现，首跳即选从哪个入口进场）；节点数字＝图内句柄 id（非节点深度、非数组序）；生成图深度域 L3 上探至 0–13——卷轴视口范式（布局决策 5）下画布随图生长、屏为窗口，深度不再受屏预算约束（2026-11-05 用户裁：滚动视口案落地、等比缩放案否决；原「超预算」挂账闭合）。 --- @@ -28,7 +28,7 @@ - **到达时机**：关卡开始即出图（停点前移——入口不自动进入，第一次选路就是「出发」）；或每次兑付确认后返回（战后回图、奖励/恢复反馈确认后回图、商店覆盖层离开后回图） - **到达前刚在做**：上一场战斗的结算画面，或奖励/恢复/商店覆盖层的确认动作 -- **情绪状态**：谋定后动——[art-bible](../../art/art-bible.md) §2.7 下探过渡的「纵深的期待」（能量 4/10）；画面应安静可读，不给选路决策添噪 +- **情绪状态**：谋定后动——[art-bible](../art/art-bible.md) §2.7 下探过渡的「纵深的期待」（能量 4/10）；画面应安静可读，不给选路决策添噪 - **到达方式**：游戏推进送入（屏级切换——独立屏激活期战斗屏整体隐藏） ## Navigation Position @@ -52,7 +52,7 @@ 本屏必须传达的全部信息，按注视优先级分六层： -1. **节点图本体**（第一注视点）：节点方块（五类型字面：战/赏/疗/王/商）、通道连线、当前位置、可选去路；类型可见性＝邻近 N 层内显示类型，范围外只见结构（机制见[关卡节点地图](../systems/冒险循环/关卡节点地图.md)） +1. **节点图本体**（第一注视点）：节点方块（五类型字面：战/赏/疗/王/商）、通道连线、当前位置、可选去路；类型可见性＝邻近 N 层内显示类型，范围外只见结构（机制见[关卡节点地图](../gdd/systems/冒险循环/关卡节点地图.md)） 2. **候选选路口**：亮金候选通道 + 候选节点亮金描边——「下一步能去哪」的图上双冗余（2026-09-27 拍板：候选按钮退役，图上点击为唯一提交通道） 3. **常驻语境**（顶栏）：关卡名（第 N 层·名称）、GP 常驻总量（2026-09-26 二轮拍板：GP = 关卡画面常驻总量） 4. **状态展示**（底栏，2026-09-27 拍板）：生命（当前/上限）、属性（攻击 / 护甲 AC 有效值）、本关已选加成（统一冒险加算区增量）——选路规划原料常读 @@ -233,7 +233,7 @@ ## Accessibility -无障碍基线权威 = [HUD框架](../systems/表现与支撑/HUD框架.md)「可访问性基线」节，本屏无新增豁免。呈现侧内建承诺： +无障碍基线权威 = [HUD框架](../gdd/systems/表现与支撑/HUD框架.md)「可访问性基线」节，本屏无新增豁免。呈现侧内建承诺： - **节点态形状冗余**（全局语义红线「无任何信息仅靠色相承载」的合规项）：已过 = 暗金无描边、当前 = 金填充 + 唯一焦点方块、候选 = 亮金粗描边、未来 = 暗底无描边；Boss = 紫赤描边 + 外缘 1px 深墨环（**灰度冗余通道**——紫赤灰度对石纹噪底不可辨）+ 图标冗余。四态在灰度截图下可分类（AC，样张 L2 断言承载） - **对比**：节点图标对方块底（双色墨制：暗底态暖白/当前金底深墨，各态 ≥4.5:1）、顶栏数字对底 ≥4.5:1（样张 L3 断言承载）；色值取 art-bible §4.1 冻结色板（已过暗金 = GOLD_DONE #68562C 冻结新值） @@ -295,12 +295,12 @@ | 义务源 | 义务 | 本 spec 承载落点 | |---|---|---| -| [关卡节点地图](../systems/冒险循环/关卡节点地图.md) | 呈现侧口径：方块地牢观感、节点态四色、不另设进度条 | Information Hierarchy 第 5 层 + 图区组件行 | +| [关卡节点地图](../gdd/systems/冒险循环/关卡节点地图.md) | 呈现侧口径：方块地牢观感、节点态四色、不另设进度条 | Information Hierarchy 第 5 层 + 图区组件行 | | 关卡节点地图 | 零自动推进、兑付后确认、选路只读 | Interaction Map + Data Requirements + AC | | 关卡节点地图 | 呈现只读（节点图/当前位置/可选下一跳对呈现层只读可见） | Data Requirements 只读出口清单 | -| [HUD框架](../systems/表现与支撑/HUD框架.md) | 模态 overlay 层级纪律、订阅纪律（推进信号两线之一） | Navigation Position + Data Requirements 架构注记 | +| [HUD框架](../gdd/systems/表现与支撑/HUD框架.md) | 模态 overlay 层级纪律、订阅纪律（推进信号两线之一） | Navigation Position + Data Requirements 架构注记 | | HUD框架 | 可访问性基线全量（对比/色弱/字号/闪烁/减动效/纯鼠标/中文字体） | Accessibility | | [battle.md](battle.md) OQ14 二轮拍板 | GP = 关卡画面常驻总量 | 顶栏 GP 常驻徽章 | -| [art-bible](../../art/art-bible.md) | 方块地牢观感（§3.2 圆角方形世界侧）、色板冻结（§4.1）、半拟物（§7.1）、明度分层（§2） | 图区组件 + Accessibility 对比条 | +| [art-bible](../art/art-bible.md) | 方块地牢观感（§3.2 圆角方形世界侧）、色板冻结（§4.1）、半拟物（§7.1）、明度分层（§2） | 图区组件 + Accessibility 对比条 | --- diff --git a/design/gdd/ux/node-reward.md b/design/ux/node-reward.md similarity index 74% rename from design/gdd/ux/node-reward.md rename to design/ux/node-reward.md index e43b2b7a..756e8404 100644 --- a/design/gdd/ux/node-reward.md +++ b/design/ux/node-reward.md @@ -2,7 +2,7 @@ > 状态：v3.0（现行） > 事实源：本 spec（呈现）＋ 三选一覆盖层（共用呈现件）＋ 头部行文案（旁白条目） -> 相邻：[level-clear](level-clear.md)（关卡完成三选一面——同一覆盖层的另一上下文）/ [level-map](level-map.md)（关卡画面）/ [秘宝](../systems/跨局循环/秘宝.md)（道具件内容权威——局外同调件，不再入三选一牌库）/ [冒险结构](../systems/冒险循环/冒险结构.md)（共享池令牌库账本） +> 相邻：[level-clear](level-clear.md)（关卡完成三选一面——同一覆盖层的另一上下文）/ [level-map](level-map.md)（关卡画面）/ [秘宝](../gdd/systems/跨局循环/秘宝.md)（道具件内容权威——局外同调件，不再入三选一牌库）/ [冒险结构](../gdd/systems/冒险循环/冒险结构.md)（共享池令牌库账本） ## 定位 @@ -13,8 +13,8 @@ - 载体 = 提升三选一覆盖层（与 [level-clear](level-clear.md) 共用组件——零新增交互原语）。 - 头部行：「关卡奖励点 / 从冒险牌库抽三选一（属性值提升与补给；与通关专长三选一同库分流）：选择一件带走：」（旁白条目）。 - 三卡点选（✓ 高亮，确认前可改选）→「确认选择」→ 兑付反馈（选中件效果 + 丢弃提示）→「继续」→ 回图选路（零自动推进同款）。 -- **三选一刷新**（X/Y 双源；机制现行事实源=[秘宝](../systems/跨局循环/秘宝.md)「三选一刷新双源」节，X 源承载件＝现行目录「刷新练习」）：装配「三选一刷新件」给 X 次（每次碰三选一重给、优先消耗、不结转）+ 营地「刷新升级」给 Y 次（每冒险开局注入冒险周期池、用完即无）；刷新钮余量 >0 时现形，点按重抽三候选（奖励抽取既有洗牌流，池规则全保留：不放回/达上限剔牌/掷定前置直显/停点可中断）。自动演示默认不刷（钓鱼归玩家）。 +- **三选一刷新**（X/Y 双源；机制现行事实源=[秘宝](../gdd/systems/跨局循环/秘宝.md)「三选一刷新双源」节，X 源承载件＝现行目录「刷新练习」）：装配「三选一刷新件」给 X 次（每次碰三选一重给、优先消耗、不结转）+ 营地「刷新升级」给 Y 次（每冒险开局注入冒险周期池、用完即无）；刷新钮余量 >0 时现形，点按重抽三候选（奖励抽取既有洗牌流，池规则全保留：不放回/达上限剔牌/掷定前置直显/停点可中断）。自动演示默认不刷（钓鱼归玩家）。 ## 口径 -- **同库同池耗**：池=固定配额令牌库（档位=四级框架 普通/优秀/稀有/传说，传说=头奖位留空〔稀有档现投放为行动点件〕；各 kind 现行配额读 `game/data/tables/adventure.tres`）；洗牌不放回抽 3（**同 kind 去重每 kind 至多一枚**——「三种不同选项」体验延续，kind 出现率∝剩余令牌数）、选中踢池未选回池、池耗即枯竭（余库不足出齐剩余，空库=零候选合法态直通）；**种类次数上限退役**（池消耗即上限）。数值对：小GP 20/大GP 50、小增伤 +1/大 +2、小护甲 +1/大 +2、小生命 +5/大 +10、恢复 +6 当即回血（封顶生效上限）、AP +1。**MC 策略 316-f**：1 级优先度=最稀有（legendary>rare>excellent>common，头奖位现行留空）、2 级=最左（并列同档取最左）。配额结构锚与档位构成读冒险表（结构校验归实现侧）。商店货架=同库付费渠道（令牌级货架，买一件=奖励面少一件），库存=剩余令牌数，账本语义与切边注记归[冒险结构](../systems/冒险循环/冒险结构.md)共享池账本节。 +- **同库同池耗**：池=固定配额令牌库（档位=四级框架 普通/优秀/稀有/传说，传说=头奖位留空〔稀有档现投放为行动点件〕；各 kind 现行配额读 `game/data/tables/adventure.tres`）；洗牌不放回抽 3（**同 kind 去重每 kind 至多一枚**——「三种不同选项」体验延续，kind 出现率∝剩余令牌数）、选中踢池未选回池、池耗即枯竭（余库不足出齐剩余，空库=零候选合法态直通）；**种类次数上限退役**（池消耗即上限）。数值对：小GP 20/大GP 50、小增伤 +1/大 +2、小护甲 +1/大 +2、小生命 +5/大 +10、恢复 +6 当即回血（封顶生效上限）、AP +1。**MC 策略 316-f**：1 级优先度=最稀有（legendary>rare>excellent>common，头奖位现行留空）、2 级=最左（并列同档取最左）。配额结构锚与档位构成读冒险表（结构校验归实现侧）。商店货架=同库付费渠道（令牌级货架，买一件=奖励面少一件），库存=剩余令牌数，账本语义与切边注记归[冒险结构](../gdd/systems/冒险循环/冒险结构.md)共享池账本节。 diff --git a/design/gdd/ux/settlement-summary.md b/design/ux/settlement-summary.md similarity index 93% rename from design/gdd/ux/settlement-summary.md rename to design/ux/settlement-summary.md index 8ad95b02..b5e599eb 100644 --- a/design/gdd/ux/settlement-summary.md +++ b/design/ux/settlement-summary.md @@ -25,7 +25,7 @@ - 触发：主角倒下（判负）/ 末关完成 / 玩家放弃——三结局同面（由冒险收束信号统一触发）。 - 载体：与战斗面同一个战斗结束覆盖层——末关关卡完成走胜利态开屏（金蜡封 +「本局 GP 入账 · 合计 N」行，GP 收束清零前的呈现侧影子账）；倒下 / 放弃走失败态开屏（暮蓝）。无独立「冒险终局面板」实体。 -- 呈现内容：冒险摘要五件事（定义归[冒险结构](../systems/冒险循环/冒险结构.md)）+ 钥石写入明细（= 本局逐杀 Boss 掉落合计；消费归[元进度](../systems/跨局循环/元进度.md) 的冒险结算入账——大奖励面不产钥石）+ GP 合计行。 +- 呈现内容：冒险摘要五件事（定义归[冒险结构](../gdd/systems/冒险循环/冒险结构.md)）+ 钥石写入明细（= 本局逐杀 Boss 掉落合计；消费归[元进度](../gdd/systems/跨局循环/元进度.md) 的冒险结算入账——大奖励面不产钥石）+ GP 合计行。 - 出口：确认 → 回存档首页。 ## 口径 diff --git a/design/gdd/ux/shop.md b/design/ux/shop.md similarity index 84% rename from design/gdd/ux/shop.md rename to design/ux/shop.md index dc984807..2e0c87bf 100644 --- a/design/gdd/ux/shop.md +++ b/design/ux/shop.md @@ -2,7 +2,7 @@ > 状态：v1.2（现行） > 事实源：本 spec（呈现）＋ 商店覆盖层（呈现件） -> 机制权威：[关卡节点地图](../systems/冒险循环/关卡节点地图.md)（商店房编排：每关恰 1/Boss 前一位必经/兑付触发）；定价数值归[难度曲线与Boss](../systems/冒险循环/难度曲线与Boss.md)（shop.tres，provisional） +> 机制权威：[关卡节点地图](../gdd/systems/冒险循环/关卡节点地图.md)（商店房编排：每关恰 1/Boss 前一位必经/兑付触发）；定价数值归[难度曲线与Boss](../gdd/systems/冒险循环/难度曲线与Boss.md)（shop.tres，provisional） ## 定位 @@ -17,6 +17,6 @@ ## 口径 -- GP 余额读数 = runner 钱包投影（GP 归[冒险结构](../systems/冒险循环/冒险结构.md) GP 节）；本层不作计算。 +- GP 余额读数 = runner 钱包投影（GP 归[冒险结构](../gdd/systems/冒险循环/冒险结构.md) GP 节）；本层不作计算。 - 与关卡画面 GP 常驻徽章的关系：进店语境余额与选路常驻总量不同义（本层带购买语境），不构成重复展示——钥石「写入/存量」拆名逻辑同款。 - 购买确认交互：现行直接购买（无二次确认步）；是否需破坏性确认异位（pattern 7）未裁决，本 spec 只登记现状不立新裁。 diff --git a/game/core/config_db_cross_validator.gd b/game/core/config_db_cross_validator.gd index 0ca4c90d..9b1e3a53 100644 --- a/game/core/config_db_cross_validator.gd +++ b/game/core/config_db_cross_validator.gd @@ -191,7 +191,7 @@ func validate_skill_pool_links(skill_table: SkillTable, enemy_table: EnemyTable, for row in enemy_table.rows: var eid: String = String(row.get("enemy_id", "")) var pool_n := {"basic": 0, "buff": 0, "debuff": 0, "uncond_special": 0} - for entry in row.get("pool", []): + for entry in enemy_table.effective_pool(row): # 合并池（elite=基础池+附加技；battle/boss=自身 pool——池构成纪律校验合并后的池） var sid: String = String(entry.get("skill_id", "")) if not skill_types.has(sid): errs.append({"category": "dangling_skill", "message": "EnemyTable %s 池引用不存在的 skill_id: %s（悬空致命）" % [eid, sid]}) diff --git a/game/core/config_db_resolver.gd b/game/core/config_db_resolver.gd index f8fb164b..db2ef49e 100644 --- a/game/core/config_db_resolver.gd +++ b/game/core/config_db_resolver.gd @@ -38,7 +38,7 @@ func resolve_enemy_rowset(L: int, D: int, row_kind: String) -> Array[Dictionary] if L < 1 or D < 0: _diag.call("fatal", "request_oob", "enemy 请求越域 (%d,%d)——进度坐标低于合法域（关卡序号≥1、节点深度≥0）" % [L, D]) return [] - if not EnemyTable.ROW_KINDS.has(row_kind): + if not EnemyTable.ENCOUNTER_ROW_KINDS.has(row_kind): # 开战寻址行类门——elite 行静置合法、任何寻址拿不到它（敌人系统.md:151） _diag.call("fatal", "request_oob", "enemy 请求行类非法 (%d,%d,\"%s\")——row_kind 域 {battle, boss}" % [L, D, row_kind]) return [] var rows: Array[Dictionary] = [] diff --git a/game/data/schemas/enemy_table.gd b/game/data/schemas/enemy_table.gd index f99d9ab4..0f944f8c 100644 --- a/game/data/schemas/enemy_table.gd +++ b/game/data/schemas/enemy_table.gd @@ -8,8 +8,10 @@ extends Resource @export var rows: Array[Dictionary] = [] # Array[Dictionary] -# 行类封闭枚举（对齐关卡节点 type 词表）：battle = 战斗节点配池，boss = 终点行集 -const ROW_KINDS := ["battle", "boss"] +# 行类封闭枚举：表内允许出现的行类（battle/boss 对齐关卡节点 type 词表，elite＝精英行） +const ROW_KINDS := ["battle", "boss", "elite"] +# 开战寻址可读的行类——elite 接线前不在此列（敌人系统 v1.9 暂不接线；resolver 行类门单点消费） +const ENCOUNTER_ROW_KINDS := ["battle", "boss"] # 护甲类型封闭枚举（克制矩阵本体在 SettlementTable； # 语义键 {light, ward, heavy} = 轻甲 / 魔法护甲 / 重甲） @@ -49,6 +51,7 @@ func validate() -> Array: errs.append_array(_validate_row_numbers(row, eid2)) errs.append_array(_validate_row_atk_range(row, eid2)) errs.append_array(_validate_row_pool(row, eid2)) + errs.append_array(_validate_elite_fields(row, eid2)) errs.append_array(_validate_row_types(row, eid2)) # 行集构成纪律②（行序即契约，敌人系统 v0.15）：同带键多行必须 # 文件内相邻。迭代中记录上一行行集键；当前行集键曾出现过但 ≠ 上一行行集键 = 同带键行被隔断，报错。 @@ -67,6 +70,7 @@ func validate() -> Array: boss_ok[L2] = true if not anchor_ok.has(L2): anchor_ok[L2] = false + errs.append_array(_validate_elite_refs()) errs.append_array(_validate_anchor_rows(anchor_ok, boss_ok)) return errs @@ -85,7 +89,7 @@ func _validate_row_base(row: Dictionary, seen: Dictionary) -> Array[Dictionary]: if L < 1 or band < 0: errs.append({"category": "domain", "message": "进度键越域 (%d,band %d)" % [L, band]}) if not ROW_KINDS.has(rk): - errs.append({"category": "domain", "message": "%s row_kind 未知枚举: \"%s\"（域 {battle, boss}）" % [eid, rk]}) + errs.append({"category": "domain", "message": "%s row_kind 未知枚举: \"%s\"（域 {battle, boss, elite}）" % [eid, rk]}) if eid == "": errs.append({"category": "domain", "message": "enemy_id 空"}) if String(row.get("display_name", "")) == "": @@ -136,25 +140,99 @@ func _validate_row_atk_range(row: Dictionary, eid: String) -> Array[Dictionary]: ## 非空池 + 条目 {skill_id 非空, weight > 0} + 池内 skill_id 不重复。 ## 普攻冷却恒 0（SkillTable schema 锁死）→ 可摇集合恒非空，"空池不可能"由此结构保证。 func _validate_row_pool(row: Dictionary, eid: String) -> Array[Dictionary]: + var no_errs: Array[Dictionary] = [] + if String(row.get("row_kind", "")) == "elite": + return no_errs # elite 行不带 pool 键（pool_extra 承载附加技——条目域校验随 _validate_elite_fields） var errs: Array[Dictionary] = [] var pool: Array[Variant] = row.get("pool", []) if pool.is_empty(): errs.append({"category": "domain", "message": "%s pool 空池（禁——技能池行必带池模板）" % eid}) + errs.append_array(_validate_pool_entries(pool, eid, "pool")) + return errs + + +## 池条目域共用校验（pool 与 pool_extra 共用——权重上限 9999 不出现第二份，契约 3 单点）； +## field 承载报错定位段（"pool"＝既有文案逐字不变，"pool_extra"＝附加技清单定位）。 +func _validate_pool_entries(entries: Array, eid: String, field: String) -> Array[Dictionary]: + var errs: Array[Dictionary] = [] var pool_ids := {} - for entry_v in pool: + for entry_v in entries: if not (entry_v is Dictionary): - errs.append({"category": "domain", "message": "%s pool 条目非字典: %s" % [eid, str(entry_v)]}) + errs.append({"category": "domain", "message": "%s %s 条目非字典: %s" % [eid, field, str(entry_v)]}) continue var entry: Dictionary[Variant, Variant] = entry_v var sid: String = String(entry.get("skill_id", "")) if sid == "": - errs.append({"category": "domain", "message": "%s pool 条目 skill_id 空" % eid}) + errs.append({"category": "domain", "message": "%s %s 条目 skill_id 空" % [eid, field]}) elif pool_ids.has(sid): - errs.append({"category": "dup_key", "message": "%s pool 内 skill_id 重复: %s" % [eid, sid]}) + errs.append({"category": "dup_key", "message": "%s %s 内 skill_id 重复: %s" % [eid, field, sid]}) pool_ids[sid] = true var w: int = int(entry.get("weight", 0)) if w <= 0 or w > 9999: - errs.append({"category": "domain", "message": "%s pool 权重越域 (0,9999]: %d" % [eid, w]}) + errs.append({"category": "domain", "message": "%s %s 权重越域 (0,9999]: %d" % [eid, field, w]}) + return errs + + +## 精英行字段互锁（敌人系统 v1.9 :281/:282/:283）：elite 行必备 base_ref/pool_extra、禁 pool、 +## enemy_id 不与 base_ref 同名；非 elite 行禁带 base_ref/pool_extra。base_ref 引用存在性归 _validate_elite_refs。 +func _validate_elite_fields(row: Dictionary, eid: String) -> Array[Dictionary]: + var errs: Array[Dictionary] = [] + if String(row.get("row_kind", "")) == "elite": + var base_ref := String(row.get("base_ref", "")) + if base_ref == "": + errs.append({"category": "cross_field", "message": "%s elite 行 base_ref 缺或空（基础敌种引用必带）" % eid}) + if base_ref == eid: + errs.append({"category": "cross_field", "message": "%s elite 行 base_ref 与自身 enemy_id 同名（禁）" % eid}) + if not row.has("pool_extra") or (row.get("pool_extra") as Array).is_empty(): + errs.append({"category": "cross_field", "message": "%s elite 行 pool_extra 缺键或空（附加技清单非空必带）" % eid}) + if row.has("pool"): + errs.append({"category": "cross_field", "message": "%s elite 行带 pool 键（禁——池走继承+附加）" % eid}) + if row.has("pool_extra") and (row.get("pool_extra") as Array).size() > 0: + errs.append_array(_validate_pool_entries(row.get("pool_extra"), eid, "pool_extra")) + else: + if row.has("base_ref"): + errs.append({"category": "cross_field", "message": "%s 非 elite 行带 base_ref 键（禁——基础敌种引用为 elite 行专属）" % eid}) + if row.has("pool_extra"): + errs.append({"category": "cross_field", "message": "%s 非 elite 行带 pool_extra 键（禁——附加技清单为 elite 行专属）" % eid}) + return errs + + +## 精英行跨行引用校验（敌人系统 v1.9 :148/:282）：base_ref 指向同关 battle 行类敌种（缺/空已由 +## _validate_elite_fields 报——此处跳过）；指向 elite 行判别同门 _min_band_row；附加技与基础池 +## skill_id 交集非空报 dup_key（敌人系统.md:149 附加技与基础池重复拒绝）。 +func _validate_elite_refs() -> Array[Dictionary]: + var errs: Array[Dictionary] = [] + for row in rows: + if String(row.get("row_kind", "")) != "elite": + continue + var base_ref := String(row.get("base_ref", "")) + if base_ref == "": + continue + var level := int(row.get("level_index", 0)) + var eid := String(row.get("enemy_id", "")) + var base := _min_band_row(level, base_ref, "battle") + if base.is_empty(): + if not _min_band_row(level, base_ref, "elite").is_empty(): + errs.append({"category": "dangling_base", "message": "%s base_ref 指向 elite 行: %s（基础敌种须为 battle 行类）" % [eid, base_ref]}) + else: + errs.append({"category": "dangling_base", "message": "%s base_ref 同关 battle 行类无此敌种: %s" % [eid, base_ref]}) + continue + errs.append_array(_extra_overlap_errs(row, base, eid)) + return errs + + +## 附加技与基础池重叠判（_validate_elite_refs 交集段提出——分支预算内聚） +func _extra_overlap_errs(row: Dictionary, base_row: Dictionary, eid: String) -> Array[Dictionary]: + var errs: Array[Dictionary] = [] + var base_ids := {} + for entry_v in base_row.get("pool", []): + if entry_v is Dictionary: + base_ids[String(entry_v.get("skill_id", ""))] = true + for entry_v in row.get("pool_extra", []): + if entry_v is Dictionary: + var sid := String(entry_v.get("skill_id", "")) + if sid != "" and base_ids.has(sid): + errs.append({"category": "dup_key", "message": "%s pool_extra 与基础池 skill_id 重复: %s" % [eid, sid]}) return errs @@ -193,6 +271,43 @@ func _validate_anchor_rows(anchor_ok: Dictionary, boss_ok: Dictionary) -> Array[ return errs +# 基础行查找单点（按 (关, 敌种, 行类) 取深度带最小行——精英有效池与「指向 elite 判别」共用， +# 禁第二份查找算法）：无匹配返回空字典。行字段一律 row.get 读取（夹具行可缺键）。 +func _min_band_row(level: int, eid: String, kind: String) -> Dictionary: + var best := {} + var best_band := -1 + for row in rows: + if int(row.get("level_index", -1)) != level or String(row.get("row_kind", "")) != kind \ + or String(row.get("enemy_id", "")) != eid: + continue + var band := int(row.get("depth_band", -1)) + if best.is_empty() or band < best_band: + best = row + best_band = band + return best + + +## 精英有效池（按需现算、零缓存零写回——敌人系统.md:149 继承不复制）：非 elite 行 = 自身 pool +## 字典条目副本；elite 行 = 基础行（同关 battle 行类基础敌种深度带最小行）pool 条目 ＋ 本行 +## pool_extra 条目（均只取 is Dictionary 条目并 duplicate——返回值改写不回灌表内行）。 +func effective_pool(row: Dictionary) -> Array[Dictionary]: + var out: Array[Dictionary] = [] + if String(row.get("row_kind", "")) != "elite": + for entry_v in row.get("pool", []): + if entry_v is Dictionary: + out.append((entry_v as Dictionary).duplicate()) + return out + var base := _min_band_row(int(row.get("level_index", 0)), String(row.get("base_ref", "")), "battle") + if not base.is_empty(): + for entry_v in base.get("pool", []): + if entry_v is Dictionary: + out.append((entry_v as Dictionary).duplicate()) + for entry_v in row.get("pool_extra", []): + if entry_v is Dictionary: + out.append((entry_v as Dictionary).duplicate()) + return out + + # 深度带切法单点（唯一实现，禁第二份算法）：band_keys = 该 (level_index, row_kind) 的 # depth_band 键升序数组；返回首个 ≥ D 的键（请求落带取偏难一侧）。 # D 高于全部键 → 返回 -1——resolver 侧 clamp 顶带＋warning，跨表校验侧判「顶 clamp 消解」违例； diff --git a/game/data/tables/enemy.tres b/game/data/tables/enemy.tres index b27a62ad..d3a2ab18 100644 --- a/game/data/tables/enemy.tres +++ b/game/data/tables/enemy.tres @@ -207,6 +207,25 @@ rows = [{ "armor_type": "light", "armor_class": 8 }, { +"level_index": 1, +"row_kind": "elite", +"depth_band": 0, +"enemy_id": "goblin_elite", + "display_name": "精英·地精", + "unit_count": 1, + "hp": 20, + "atk": 2, + "atk_min": 1, + "atk_max": 3, +"base_ref": "goblin", +"pool_extra": [{ +"skill_id": "heavy", +"weight": 2 +}], +"attack_type": "normal", +"armor_type": "light", +"armor_class": 2 +}, { "level_index": 2, "row_kind": "battle", "depth_band": 0, @@ -943,6 +962,7 @@ rows = [{ ; 不做差异化（pierce/magic 属新设计另立项）。全局平移效应=主角穿重甲受伤 −1 / 魔法护甲 +1 / 轻甲 0， ; 锻造甲路线首次具备战斗意义；克制矩阵数值零触碰（settlement.tres armor_effectiveness 不改）。 ; -; 行键 = (level_index, row_kind, depth_band, enemy_id)；row_kind ∈ {battle, boss}——battle=战斗节点配池，boss=终点行集； +; 行键 = (level_index, row_kind, depth_band, enemy_id)；row_kind ∈ {battle, boss, elite}——battle=战斗节点配池，boss=终点行集，elite=精英行（独立 enemy_id、池走继承+附加，暂不接线任何节点寻址）； ; depth_band=节点深度所在的带键，请求落带取首个 ≥ 深度的键（偏难一侧）；越顶带由 resolver clamp、跨表校验判为调参事故。 ; (1,3) 大地精行 2026-11-04 用户裁退役，改地精＋熊地精混编（行序熊地精在前、行值整行复用 (1,2)/(1,0)、静态骰和 3）；沿革见 git 提交史 +; 精英专属池批首只精英＝地精精英（1,elite,0,goblin_elite），行值 provisional（投值所有权归难度曲线与Boss 统一修正），来源=2026-11-06 用户点头草案 v0 diff --git a/game/presentation/main.gd b/game/presentation/main.gd index bd941859..3c4887df 100644 --- a/game/presentation/main.gd +++ b/game/presentation/main.gd @@ -190,8 +190,8 @@ func _start_adventure_from_menu() -> void: # 主菜单「开始冒险」钮已随三入口化撤出（卡② mn6——主菜单侧断点互斥确认链同步摘除， # 弹窗本体与两分支逻辑归卡④大门承接）。本函数为探针直调中间态保留（mn10——冒险段探针 # 直调位点逐个登记实现报告「已知中间态」；卡④到位后由大门两分支换代）。无激活态写盘拒绝 - # 由卡① sv3 承接（结算不落盘）。 - ui.screens.start_overlay.visible = false + # 由卡① sv3 承接（结算不落盘）。开始层隐藏已收进 _start_adventure()（营地交互修复批契约 1 + # ——开局路径隐藏点唯一出口）。 _start_adventure() @@ -290,6 +290,7 @@ static func build_adventure_params(save_manager_ref: SaveManagerCore, meta_ref: # 冒险模式（三关连探——AdventureRunner 编排；转发信号签名与 runner 一致，接线照原样对接； # 信号连接只在组合根） func _start_adventure() -> void: + ui.screens.start_overlay.visible = false # 开局路径开始层隐藏唯一出口（营地交互修复批契约 1——三处调用方经此收口；失败分支开始层终态=隐藏，致命屏接管） ui.flow.close(ui.modals.menu.debug_overlay) # 开冒险路径显式关浮窗（调试浮窗默认开态下开局不带窗；对局中经角标再开） begin_session(true) _wire_adventure() diff --git a/game/presentation/views/ap_bar_view.gd b/game/presentation/views/ap_bar_view.gd index 4045fbf0..8f7b86a6 100644 --- a/game/presentation/views/ap_bar_view.gd +++ b/game/presentation/views/ap_bar_view.gd @@ -189,20 +189,10 @@ func is_refresh_ready() -> bool: return not _btn_refresh.disabled -# 探针接缝（合成输入走真实翻译出口口径）：刷新按钮点击 → 确认 chips 全链路 -func press_refresh_for_probe() -> void: - _on_refresh_pressed() - - func confirm_visible() -> bool: return _confirm_row.visible -func press_confirm_for_probe() -> void: - if _arm_timer.is_armed(): - _disarm_and_fire() - - func refresh_remaining_text() -> String: return _refresh_sub.text diff --git a/game/presentation/views/battle_end_overlay.gd b/game/presentation/views/battle_end_overlay.gd index 3c9c3ba6..dba79c75 100644 --- a/game/presentation/views/battle_end_overlay.gd +++ b/game/presentation/views/battle_end_overlay.gd @@ -191,10 +191,11 @@ func close() -> void: st.seal.visible = false st.seal.modulate = Color.WHITE st.cele.visible = false - var tw: Tween = get_meta(&"celebrate_tw", null) # 循环句柄随节点存（跨 open/close，close 必杀） - if tw != null and tw.is_valid(): - tw.kill() - remove_meta(&"celebrate_tw") + if has_meta(&"celebrate_tw"): # 循环句柄随节点存（跨 open/close：有则必杀、无则无事——缺 meta 跳过） + var tw: Tween = get_meta(&"celebrate_tw") + if tw.is_valid(): + tw.kill() + remove_meta(&"celebrate_tw") _clear_crest_bricks() @@ -328,9 +329,10 @@ func _spawn_dust_mote(i: int, base: Vector2) -> void: func _play_celebrate() -> void: if UiKit.motion_scale < 1.0: return - var prev: Tween = get_meta(&"celebrate_tw", null) - if prev != null and prev.is_valid(): - prev.kill() + if has_meta(&"celebrate_tw"): # 有句柄才取并 kill（缺 meta 静默跳过——败走后首次胜利同款容错） + var prev: Tween = get_meta(&"celebrate_tw") + if prev.is_valid(): + prev.kill() var tw := st.cele.create_tween() set_meta(&"celebrate_tw", tw) tw.set_loops() diff --git a/game/presentation/views/camp_hud_band.gd b/game/presentation/views/camp_hud_band.gd index a228626a..530d735a 100644 --- a/game/presentation/views/camp_hud_band.gd +++ b/game/presentation/views/camp_hud_band.gd @@ -11,10 +11,15 @@ func _init() -> void: set_anchors_preset(Control.PRESET_TOP_WIDE) custom_minimum_size = Vector2(0, 48) # 高 48px 浮层覆盖、不挤压画面（camp.md §顶栏） mouse_filter = Control.MOUSE_FILTER_IGNORE # HUD 栏不挡场景命中区（浮层覆盖语义） + UiKit.camp_hud_band_surface(self) # 栏体色面——整件外观单一出口（色值与 α、铺满、不吃点击、挂载全在出口内）；先入=绘制序底，徽章后入不被盖 _badge = UiKit.keystone_badge("钥石 0") - _badge.set_anchors_preset(Control.PRESET_CENTER_RIGHT) - _badge.position = Vector2(-160, 8) # 顶栏右位次（UiKit 现行件域内——代拍板 3） - add_child(_badge) + var dock := HBoxContainer.new() # 右对齐容器承载徽章（Q2 已裁乙——位数增宽自然向左展；摆位机制先例=confirm_dialog 钮行同款容器 alignment） + dock.set_anchors_preset(Control.PRESET_FULL_RECT) + dock.offset_right = -12.0 # 右缘内缩 12px（UiKit 钮间距同档——白名单 3） + dock.alignment = BoxContainer.ALIGNMENT_END + dock.mouse_filter = Control.MOUSE_FILTER_IGNORE # 容器自身默认 STOP——与出口内 IGNORE 是两个点，必须同批落（漏一处顶排物件点不动） + dock.add_child(_badge) + add_child(dock) ## 余额写入（格式串=既有消费面同款「钥石 %d」——badge 工厂约定单点，禁第二格式串） diff --git a/game/presentation/views/confirm_dialog.gd b/game/presentation/views/confirm_dialog.gd index 6ce39f15..8667c07b 100644 --- a/game/presentation/views/confirm_dialog.gd +++ b/game/presentation/views/confirm_dialog.gd @@ -30,13 +30,15 @@ func _init() -> void: box.add_child(btn_row) _cancel_btn = UiKit.button("取消") _cancel_btn.pressed.connect(_emit_cancelled) - btn_row.add_child(_cancel_btn) _secondary_btn = UiKit.button("次选项") _secondary_btn.pressed.connect(_emit_secondary) - btn_row.add_child(_secondary_btn) _confirm_btn = UiKit.button("确认") _confirm_btn.pressed.connect(_emit_confirmed) + # 位次定值（HUD框架.md:90 三条纪律·其三——推进钮在左、次推进居中、维持在右；四处消费方 + # 共用本件同一序。信号按按钮对象路由、不按位次——换序不改路由〔营地交互修复批契约 3〕） btn_row.add_child(_confirm_btn) + btn_row.add_child(_secondary_btn) + btn_row.add_child(_cancel_btn) visible = false diff --git a/game/presentation/views/curio_pick_overlay.gd b/game/presentation/views/curio_pick_overlay.gd index 9d187fb7..a2ca37af 100644 --- a/game/presentation/views/curio_pick_overlay.gd +++ b/game/presentation/views/curio_pick_overlay.gd @@ -153,26 +153,6 @@ func _on_confirm_pressed() -> void: pick_confirmed.emit(_selected) -# 探针/测试复用：以真实按钮路径触发点选、确认与继续（树序遮挡纪律——断言走真实信号路径） -func press_card(index: int) -> void: - # M7：卡载体 Button→bcard（gui_input 点选）——真实路径=同一 _select_card 处理器，探针语义不变 - if index >= 0 and index < _card_meta.size(): - _select_card(String(_card_meta[index].get("id", ""))) - - -func press_confirm() -> void: - _confirm_btn.pressed.emit() - - -func press_continue() -> void: - _continue_btn.pressed.emit() - - -# 探针/测试复用：以真实按钮路径触发刷新意图（信号外发——受理归组合根） -func press_refresh() -> void: - _refresh_btn.pressed.emit() - - # 兑付反馈态（curio_resolved 到达——结果行追加在头部之后；唯一出口 = 继续） func show_result(text: String) -> void: _label.text = _header + "\n" + text diff --git a/game/presentation/views/debug_overlay.gd b/game/presentation/views/debug_overlay.gd index 922b33cd..d0117d8d 100644 --- a/game/presentation/views/debug_overlay.gd +++ b/game/presentation/views/debug_overlay.gd @@ -123,20 +123,6 @@ func output_text() -> String: return st.sim_out.get_parsed_text() -# ---- 探针接缝（真实翻译出口——按钮 pressed 信号路径，非直调组合根）---- - -func press_apply_for_probe() -> void: - _apply_btn_pressed() - - -func press_reset_for_probe() -> void: - _reset_btn_pressed() - - -func press_simulate_for_probe() -> void: - _sim_btn.pressed.emit() - - # ---- 内部（信号 → 外发）---- func _apply_btn_pressed() -> void: diff --git a/game/presentation/views/level_map_screen.gd b/game/presentation/views/level_map_screen.gd index c7ad7bf6..f4deee69 100644 --- a/game/presentation/views/level_map_screen.gd +++ b/game/presentation/views/level_map_screen.gd @@ -465,18 +465,20 @@ func _submit_choice(nid: int) -> void: route_chosen.emit(nid) -# 探针复用：按候选序号走图上命中同路径（候选节点中心坐标 → 命中检测 → 提交——布局决策 2 探针面改造） -func press_candidate(index: int) -> void: +# 探针面命中矩形读口：候选节点的图上命中矩形（全局坐标——真输入 push_click_at 落点）。 +# 命中面与 _candidate_at 同源（节点方块＋外扩容差）；index 越界或候选未就绪返回空 Rect2（调用方跳过）。 +func candidate_rect(index: int) -> Rect2: if index < 0 or index >= _cand_ids.size() or _map.runner == null: - return + return Rect2() var nodes: Array[Variant] = _map.runner.nodes() var node := _node_by_id(int(_cand_ids[index]), nodes) if node.is_empty(): - return + return Rect2() var pos: Vector2 = _layout(nodes, _map.canvas)[node] - var nid := _candidate_at(pos) # 节点中心必命中自身（命中面含节点方块） - if nid >= 0: - _submit_choice(nid) + var half := NODE_HALF + Vector2(HIT_PAD, HIT_PAD) + var local := Rect2(pos - half, half * 2.0) + var xform := _map.canvas.get_global_transform() + return Rect2(xform * local.position, local.size) # ---- 视口锚点（布局决策 5：当前节点居中；入口停点尚无当前节点＝锚入口组包围盒居中） ---- diff --git a/game/presentation/views/node_overlay.gd b/game/presentation/views/node_overlay.gd index cabfcdf5..19954500 100644 --- a/game/presentation/views/node_overlay.gd +++ b/game/presentation/views/node_overlay.gd @@ -29,10 +29,6 @@ func show_rest(healed: int, hp_after: int, max_hp: int) -> void: _btn.text = "休息完毕，继续" visible = true -# 探针复用：以真实按钮路径触发继续 -func press_continue() -> void: - _btn.pressed.emit() - func _emit_continue_pressed() -> void: continue_pressed.emit() diff --git a/game/presentation/views/seal_mark.gdshader b/game/presentation/views/seal_mark.gdshader index affc4164..d47c6a33 100644 --- a/game/presentation/views/seal_mark.gdshader +++ b/game/presentation/views/seal_mark.gdshader @@ -2,7 +2,7 @@ // 封印印记（卡④ 法阵化批）——环＋十字＋环外压暗光圈，canvas_item 距离场实时绘制（无贴图缩放， // 格边 26–46px 连续可变下任意格边清晰）。 // 事实源：art-bible v3.41 §3.2「封印印记」（形／画法／光圈／层序纪律）＋ §8.2「封印印记参数表」； -// gdd/ux/battle.md「棋盘格尺寸公式」（格边 clampi 26–46）。 +// design/ux/battle.md「棋盘格尺寸公式」（格边 clampi 26–46）。 // 纪律：参数五枚＋色全由 gd 侧逐次注入（参数单点 = ui_kit SEAL_* 五常量——禁在此改值， // 下方默认值仅为兜底且与 §8.2 同值）；光圈不出格（半径夹 cell_px/2）； // 零动效（不呼吸不脉冲——§2.1 挖掘期唯一在动 = 接触带微光）；印记与光圈同用一色（光圈只改 alpha）。 diff --git a/game/presentation/views/ui_kit.gd b/game/presentation/views/ui_kit.gd index b8c615c8..57024b08 100644 --- a/game/presentation/views/ui_kit.gd +++ b/game/presentation/views/ui_kit.gd @@ -193,6 +193,7 @@ const TIP_BG := Color(0.16, 0.12, 0.09, 0.96) # tooltip 深底 const STAND_STONE := Color8(150, 130, 100) # 站桩石板地台·板身（standee_body 方向稿取色） const PLAZA_EDGE := Color8(76, 64, 56) # 小石台描边（art-bible §4.1 换色合并②合并目标——贴图已落此值，缺位回退同值） const CAMP_HEADER_BAND := Color8(110, 69, 38) # 营地柜台头带深棕 #6E4526（4-camp.png 方向稿取色；对齐 demo --wood-deep） +const CAMP_HUD_BAND := Color(CAMP_HEADER_BAND, 0.80) # 营地顶栏栏体=头带深棕×α0.80（camp.md §顶栏定值——派生收口单点，非色板新增；同文件 TOAST_BG/TIP_BG 带 α 先例） const CAMP_ROW_PLATE := Color8(240, 230, 206) # 营地行板暖米（同上） const CAMP_BADGE_PANEL := Color8(40, 32, 24) # 营地钥石徽暗底（同上） const HP_BAR_BACK := Color8(40, 34, 32) # 迷你血条深底 #282220（兼血数垫牌；站桩名字行素底同源——§6.1/§7.2 文字禁压地台） @@ -656,6 +657,19 @@ static func keystone_badge(text: String, icon_path := TEX_ICON_KEYSTONE, icon_px return KeystoneBadge.new(text, icon_path, icon_px) +## 营地顶栏栏体面（整件外观单一出口——营地交互修复批契约 4/5）：色值与 α、铺满、不吃点击、 +## 挂上宿主五件事全写死在体内；形参只有 host——调用方没有可以忘记的形参。返回句柄供调用方 +## 读取与断言；徽章摆位不由本出口负责（归顶栏件内右对齐容器）。须在宿主入树前调用 +## （set_anchors_preset 是入树前动作——_modal_dim/overlay_bg 同形）。 +static func camp_hud_band_surface(host: Control) -> ColorRect: + var rect := ColorRect.new() + rect.color = CAMP_HUD_BAND + rect.set_anchors_preset(Control.PRESET_FULL_RECT) # 四边 offset 归零铺满宿主 + rect.mouse_filter = Control.MOUSE_FILTER_IGNORE # 栏体不吃点击（顶排物件命中区不受阻——契约 5） + host.add_child(rect) + return rect + + # 按钮皮·五态矩阵（逐实例 override 不动主题层） # 悬停：常态图+modulate 提亮（0.06 档与 primary_button 现行 lightened(0.06) 同纪律，零新素材）； # 禁用：本族底+α0.45 幽灵化（与 font_disabled_color 同纪律）； diff --git a/game/probe/fx_shot_probe.gd b/game/probe/fx_shot_probe.gd index b7e15910..71c2daa7 100644 --- a/game/probe/fx_shot_probe.gd +++ b/game/probe/fx_shot_probe.gd @@ -45,7 +45,7 @@ func _ready() -> void: return for i in 5: await get_tree().process_frame - main.ui.modals.run.level_screen.press_candidate(0) + ProbeUiUtil.push_click_at(main, main.ui.modals.run.level_screen.candidate_rect(0).get_center()) for i in 20: await get_tree().process_frame var st = main.run_scope.settlement diff --git a/game/probe/layout_probe.gd b/game/probe/layout_probe.gd index cb68fd60..3b9f88e1 100644 --- a/game/probe/layout_probe.gd +++ b/game/probe/layout_probe.gd @@ -1,7 +1,7 @@ # VERTICAL SLICE - NOT FOR PRODUCTION # 布局几何断言探针（现行事实源=tools/probe_gate.sh 默认段；呈现层三区布局的分辨率维度验收） # 用途：battle.md §验收「1280×800 与 16:9 全屏下三区无遮挡/无重叠/无裁切」的可执行化 -# GDD 锚：design/gdd/ux/battle.md §Layout Zones（B/C/D 三区几何） +# GDD 锚：design/ux/battle.md §Layout Zones（B/C/D 三区几何） # 硬约束：档位表是数据、断言是一份函数据——加档只改表不动断言（禁每档建一个探针） extends Node @@ -30,7 +30,7 @@ func _ready() -> void: for i in range(8): await get_tree().process_frame # 进战斗屏——三区（B 战斗画面/C 角色信息/D 扫雷图）同屏常驻，菜单屏不构成断言面 - main.ui.modals.run.level_screen.press_candidate(0) + ProbeUiUtil.push_click_at(main, main.ui.modals.run.level_screen.candidate_rect(0).get_center()) for i in range(20): await get_tree().process_frame for vp in VIEWPORTS: diff --git a/game/probe/level_map_viewport_probe.gd b/game/probe/level_map_viewport_probe.gd index 6b9a3031..a83c93d3 100644 --- a/game/probe/level_map_viewport_probe.gd +++ b/game/probe/level_map_viewport_probe.gd @@ -22,14 +22,14 @@ var _runner # 当前停点的单关 runner（open_choices 驱动随记—— func _check(desc: String, ok: bool) -> void: -# oracle: design/gdd/ux/level-map.md:3 （判定上报通道——验证函数组） +# oracle: design/ux/level-map.md:3 （判定上报通道——验证函数组） _checks += 1 if not ok: _problems.append(desc) func _ready() -> void: -# oracle: design/gdd/ux/level-map.md:3 （关卡画面视口跟随——卷轴视口组） +# oracle: design/ux/level-map.md:3 （关卡画面视口跟随——卷轴视口组） await get_tree().process_frame await get_tree().process_frame var host := Control.new() @@ -62,7 +62,7 @@ func _ready() -> void: ## R1 浅图整幅居中无裁切＋画布入视口件承载（画布=视口首子件——setup 注入序） func _probe_shallow_no_crop(screen, vp) -> void: -# oracle: design/gdd/ux/level-map.md:3 （浅层不裁切组） +# oracle: design/ux/level-map.md:3 （浅层不裁切组） _runner = _make_runner_entry(1, SEED_L1) screen.open_choices(_cand_nodes(_runner), _runner) await get_tree().process_frame @@ -81,7 +81,7 @@ func _probe_shallow_no_crop(screen, vp) -> void: ## R5 前置＋深图入口停点：锚点=入口组包围盒中心夹紧（spec :101——多入口并列取包围盒居中） func _probe_deep_entry_clamp(screen, vp) -> void: -# oracle: design/gdd/ux/level-map.md:3 （深层入口钳制组） +# oracle: design/ux/level-map.md:3 （深层入口钳制组） _runner = _make_runner_entry(3, SEED_L3) screen.open_choices(_cand_nodes(_runner), _runner) await get_tree().process_frame @@ -175,7 +175,7 @@ func _probe_clamp_bounds_and_columns(screen, vp) -> void: ## R6 拖拽不触发选路提交；阈值另一侧完整点击仍提交（提交语义零改动） func _probe_drag_no_submit(screen, vp) -> void: -# oracle: design/gdd/ux/level-map.md:3 （判定上报通道——验证函数组） +# oracle: design/ux/level-map.md:3 （判定上报通道——验证函数组） # 重建到中段可居中停点（候选=停点出边——候选节点居屏中可拖可达） var stops := _centerable_stops(screen, vp) if stops.size() < 3: @@ -214,7 +214,7 @@ func _probe_drag_no_submit(screen, vp) -> void: ## R2 停点切换后当前节点居中（视口中线投影 x=640±2——视口满屏宽即屏中线） func _probe_follow_anchor(screen, vp) -> void: -# oracle: design/gdd/ux/level-map.md:3 （判定上报通道——验证函数组） +# oracle: design/ux/level-map.md:3 （判定上报通道——验证函数组） var stops := _centerable_stops(screen, vp) if stops.size() < 3: _problems.append("R2 可居中停点不足（=%d）" % stops.size()) @@ -230,7 +230,7 @@ func _probe_follow_anchor(screen, vp) -> void: ## R7 平滑滚动有 tween 中间帧；减动效开＝位置即达（画布坐标域判定） func _probe_smooth_scroll_reduced_motion(screen, vp) -> void: -# oracle: design/gdd/ux/level-map.md:3 （判定上报通道——验证函数组） +# oracle: design/ux/level-map.md:3 （判定上报通道——验证函数组） var saved_scale: float = UiKit.motion_scale UiKit.motion_scale = 1.0 var stops := _centerable_stops(screen, vp) @@ -270,7 +270,7 @@ func _probe_smooth_scroll_reduced_motion(screen, vp) -> void: ## R8 指引件可见性与几何（深图超窗——像素级判据②③） func _probe_guidance_chrome(screen, vp) -> void: -# oracle: design/gdd/ux/level-map.md:3 （判定上报通道——验证函数组） +# oracle: design/ux/level-map.md:3 （判定上报通道——验证函数组） var band_l: Control = vp.get_node_or_null(NodePath("FadeL")) var band_r: Control = vp.get_node_or_null(NodePath("FadeR")) var chip: Control = vp.get_node_or_null(NodePath("PanHint")) @@ -302,7 +302,7 @@ func _probe_shallow_guidance_hidden(screen, vp) -> void: ## 入口停点 runner（defer_entry——选路态挂起、候选=入口节点） func _make_runner_entry(level_index: int, seed_val: int): -# oracle: design/gdd/ux/level-map.md:3 （判定上报通道——验证函数组） +# oracle: design/ux/level-map.md:3 （判定上报通道——验证函数组） var rng = load("res://core/rng_service.gd").new() rng.new_adventure(seed_val) var runner = load("res://core/level_runner.gd").new(get_node("/root/ConfigDB"), rng) @@ -313,7 +313,7 @@ func _make_runner_entry(level_index: int, seed_val: int): ## 中段停点 runner（断点续玩重建——图由种子+参数档重生成同图，零 RNG 消耗） func _make_runner_at_stop(level_index: int, seed_val: int, node_id: int): -# oracle: design/gdd/ux/level-map.md:3 （判定上报通道——验证函数组） +# oracle: design/ux/level-map.md:3 （判定上报通道——验证函数组） var rng = load("res://core/rng_service.gd").new() rng.new_adventure(seed_val) var runner = load("res://core/level_runner.gd").new(get_node("/root/ConfigDB"), rng) @@ -388,7 +388,7 @@ func _extreme_node(pos: Dictionary, nodes: Array, first: bool) -> Dictionary: func _finish() -> void: -# oracle: design/gdd/ux/level-map.md:3 （判定上报通道——验证函数组） +# oracle: design/ux/level-map.md:3 （判定上报通道——验证函数组） if _checks == 0: _problems.append("零断言执行（断言数下限闸——三硬闸③）") if _problems.is_empty(): diff --git a/game/probe/probe_coverage_recorder.gd b/game/probe/probe_coverage_recorder.gd index c7f2f27f..c13abde8 100644 --- a/game/probe/probe_coverage_recorder.gd +++ b/game/probe/probe_coverage_recorder.gd @@ -199,6 +199,7 @@ func _seen_into(node: Node, keys: Array[String]) -> void: # ---- 落盘（JSONP 式 .js——file:// 页面